{"owner":"github","repo":"spec-kit","hasSkills":true,"totalSkillsCount":11,"totalTokensCount":12558,"categories":["anthropic-skill","root-instruction","plugin-manifest"],"hasMcp":false,"mcpConfig":null,"found":[".github/skills/add-community-extension/SKILL.md",".github/skills/code-review/SKILL.md","AGENTS.md","extensions/README.md","extensions/agent-context/README.md","extensions/assess/README.md","extensions/bug/README.md","extensions/git/README.md","extensions/github/README.md","extensions/template/EXAMPLE-README.md","extensions/template/README.md"],"skills":{".github/skills/add-community-extension/SKILL.md":"---\nname: add-community-extension\ndescription: 'Add a community extension to the Spec Kit catalog from a GitHub issue submission. USE FOR: processing extension submission issues, validating catalog entries, updating catalog.community.json and docs/community/extensions.md, creating PRs. DO NOT USE FOR: creating new extensions from scratch, or first-party extension work.'\nargument-hint: 'GitHub issue URL or number for the extension submission'\n---\n\n# Add Community Extension\n\nProcess an extension submission issue and add or update it in the community catalog.\n\n## When to Use\n\n- A new `[Extension]` submission issue is filed\n- An existing extension submits an update issue (new version, changed metadata)\n- You need to add or update a community extension in `extensions/catalog.community.json` and `docs/community/extensions.md`\n\n## Procedure\n\n### 1. Fetch the submission issue\n\nRead the GitHub issue to extract all metadata:\n- Extension ID, name, version, description, author\n- Repository URL, download URL, homepage, documentation, changelog\n- License, required spec-kit version, optional tool dependencies\n- Number of commands and hooks\n- Tags\n\n### 2. Validate against publishing rules\n\nCheck **all** of the following (per `extensions/EXTENSION-PUBLISHING-GUIDE.md`):\n\n| Check | How |\n|-------|-----|\n| Repository exists and is public | Fetch the repository URL |\n| `extension.yml` manifest present | Confirm in repo file listing |\n| README.md present | Confirm in repo file listing |\n| LICENSE file present | Confirm in repo file listing |\n| GitHub release exists matching version | Check releases on the repo page |\n| Download URL is accessible | Verify it follows `archive/refs/tags/vX.Y.Z.zip` pattern and release exists |\n| Extension ID is lowercase-with-hyphens only | Regex: `^[a-z][a-z0-9-]*$` |\n| Version follows semver | Format: `X.Y.Z` |\n| Submission checklists are all checked | Confirm in issue body |\n\n### 3. Determine if this is an add or update\n\nSearch `extensions/catalog.community.json` for the extension ID.\n\n- **Not found** → this is a **new addition**. Proceed to step 4.\n- **Found** → this is an **update**. Proceed to step 4 but replace the existing entry in-place instead of inserting.\n\n### 4. Add or update `extensions/catalog.community.json`\n\n**New extension:** Insert the entry in **alphabetical order** by extension ID.\n\n**Update:** Replace the existing entry in-place. Update only the fields that changed (typically `version`, `download_url`, `description`, `provides`, `requires`, `tags`, `updated_at`). Preserve `created_at` and `downloads`/`stars` from the existing entry.\n\nUse the existing entries as the format template. Required fields:\n\n```json\n{\n \"\": {\n \"name\": \"\",\n \"id\": \"\",\n \"description\": \"\",\n \"author\": \"\",\n \"version\": \"\",\n \"download_url\": \"\",\n \"repository\": \"\",\n \"homepage\": \"\",\n \"documentation\": \"\",\n \"changelog\": \"\",\n \"license\": \"\",\n \"category\": \"\",\n \"effect\": \"\",\n \"requires\": {\n \"speckit_version\": \"\"\n },\n \"provides\": {\n \"commands\": ,\n \"hooks\": \n },\n \"tags\": [\"\", \"\"],\n \"verified\": false,\n \"downloads\": 0,\n \"stars\": 0,\n \"created_at\": \"T00:00:00Z\",\n \"updated_at\": \"T00:00:00Z\"\n }\n}\n```\n\n**Category** — free-form string; common values: `docs`, `code`, `process`, `integration`, `visibility`\n**Effect** — one of: `read-only`, `read-write`\n\nIf the extension has optional tool dependencies, add a `\"tools\"` array inside `\"requires\"`:\n\n```json\n\"tools\": [{ \"name\": \"\", \"required\": false }]\n```\n\nAlso update the top-level `\"updated_at\"` timestamp in the catalog.\n\nAfter editing, **validate the JSON** by running:\n\n```bash\npython3 -c \"import json; json.load(open('extensions/catalog.community.json')); print('Valid JSON')\"\n```\n\n### 5. Add or update `docs/community/extensions.md` community extensions table\n\n**New extension:** Insert a new row into the `# Community Extensions` table in **alphabetical order** by extension name.\n\n**Update:** Find the existing row and update the description or other changed fields in-place.\n\nDetermine the category and effect from the extension's behavior:\n\n```\n| | | `` | | []() |\n```\n\n**Category** — free-form; common values: `docs`, `code`, `process`, `integration`, `visibility`\n**Effect** — write canonical values `read-only` or `read-write` in `extension.yml` and `catalog.community.json`; use `Read-only`/`Read+Write` only for the docs table display\n\n### 6. Commit, push, and open PR\n\nUse `add-` for new extensions, `update-` for updates:\n\n```bash\n# New extension\ngit checkout -b add--extension\n\n# Update\ngit checkout -b update--extension\n```\n\n```bash\ngit add extensions/catalog.community.json docs/community/extensions.md\n\n# New extension\ngit commit -m \"Add extension to community catalog\n\nAdd extension submitted by @ to:\n- extensions/catalog.community.json (alphabetical order)\n- docs/community/extensions.md community extensions table\n\nCloses #\"\n\n# Update\ngit commit -m \"Update extension to v\n\nUpdate extension submitted by @:\n- extensions/catalog.community.json (version, download_url, etc.)\n- docs/community/extensions.md community extensions table\n\nCloses #\"\n\ngit push origin \n```\n\nThen create a PR to `upstream` (`github/spec-kit`) with:\n- **Title:** `Add extension to community catalog` (or `Update extension to v`)\n- **Body:** Include validation summary, `Closes #`, and `cc @`\n- **Head:** `:`\n- **Base:** `main`\n\n## Common Pitfalls\n\n- **Alphabetical order matters** — entries must be sorted by ID in the JSON and by name in the docs table.\n- **Don't forget the catalog `updated_at`** — the top-level timestamp in `catalog.community.json` must be refreshed.\n- **Validate JSON after editing** — a trailing comma or missing brace will break the catalog.\n- **Use `Closes` not `Fixes`** — `Closes #N` is the correct keyword for submission issues.\n- **Match the proposed entry but verify** — the issue may include a proposed JSON block, but always validate field values against the actual repository state.\n- **Preserve `created_at` on updates** — keep the original `created_at` value; only change `updated_at`.\n- **Preserve `downloads` and `stars` on updates** — these reflect usage metrics and must not be reset.\n",".github/skills/code-review/SKILL.md":"---\nname: code-review\ndescription: Reviews Spec Kit code changes for consistency with applicable design documents, positive and negative test coverage, regression evidence for bug fixes, and consistent repository terminology. Use when reviewing a diff or pull request. Do not use for implementing changes or posting GitHub review actions.\nargument-hint: 'Diff or pull request to review'\n---\n\n# Code Review\n\n1. Ensure each code change has test cases that verify what the code should do and what it should prevent.\n2. Ensure bug-fix pull requests include a regression test that demonstrates the bug was reproducible before the change and is fixed afterward; if the reviewer cannot run the comparison, use available evidence and state that limitation.\n3. Ensure wording changes use repository-consistent terms; exclude community-authored catalog content and its generated documentation from this check.\n4. Identify the affected domains and read the applicable documents in `design/` before evaluating architectural consistency. For CLI command changes, use `design/cli.md`; for agent integrations, use `design/integration.md`; for workflow step types, use `design/workflow-step.md`. Read other design documents when relevant, not every document for every PR.\n5. Check the changes against the applicable design requirements, including implementation boundaries, ownership, lifecycle, and delivery requirements. Reference the documents rather than duplicating their rules in this skill. Cite the document and section for each reported mismatch.\n6. Distinguish an unexplained design violation from an intentional design change. Evaluate the rationale and evidence for an intentional change; updating the design document alone does not establish that the implementation is justified.\n","AGENTS.md":"# AGENTS.md\n\n## About Spec Kit and Specify\n\n**GitHub Spec Kit** is a comprehensive toolkit for implementing Spec-Driven Development (SDD) - a methodology that emphasizes creating clear specifications before implementation. The toolkit includes templates, scripts, and workflows that guide development teams through a structured approach to building software.\n\n**Specify CLI** is the command-line interface that bootstraps projects with the Spec Kit framework. It sets up the necessary directory structures, templates, and AI agent integrations to support the Spec-Driven Development workflow.\n\nThe toolkit supports multiple AI coding assistants, allowing teams to use their preferred tools while maintaining consistent project structure and development practices.\n\n## Adding or Updating CLI Commands\n\nBefore adding, updating, or reorganizing Specify CLI commands, read\n[Shared Command Application Architecture](design/shared.md) and\n[Specify CLI Command Architecture](design/cli.md). They define the shared\noperation boundary, command-module naming, private phases, nested command\ngroups, registration ownership, and mirrored tests.\n\n## Adding or Updating MCP Commands\n\nBefore adding or changing MCP tools for Specify commands, read\n[Shared Command Application Architecture](design/shared.md) and\n[Specify MCP Command Architecture](design/mcp.md). They define the shared\noperation boundary, typed contracts, explicit inventory, side-effect metadata,\nthe local stdio protocol boundary, and mirrored tests.\n\n## Adding or Updating Agent Integrations\n\nBefore adding or changing AI agent integrations, read\n[Agent Integration Design](design/integration.md). It covers\ndelivery routes, output formats, registration, and install/uninstall ownership.\n\n## Adding or Updating Workflow Steps\n\nBefore adding or changing workflow step types, read\n[Workflow Step Design](design/workflow-step.md). It covers registration,\nvalidation, execution, resume, and installed step packages.\n\n## Testing Executable Behavior\n\nBefore changing code or configuration that runs or controls execution without\nan LLM, read\n[Testing deterministic behavior](CONTRIBUTING.md#testing-deterministic-behavior).\nBehavioral changes need positive and negative coverage; bug fixes need\nbefore-and-after regression evidence.\n\n## PowerShell Compatibility\n\nAll PowerShell scripts in the repository and all generated PowerShell\nfunctionality MUST target Windows PowerShell 5.1, the version included with\nWindows. When adding or changing PowerShell code, use only syntax, cmdlets,\nparameters, and .NET APIs available in Windows PowerShell 5.1. Account for\nencoding and other runtime differences, preserve the required behavioral\nparity with Bash and Python implementations, and provide Windows PowerShell\n5.1 validation evidence for behavioral changes.\n\n## Branches and Agent Contributions\n\nWhen creating a branch, follow [Branch naming](CONTRIBUTING.md#branch-naming).\nBefore authoring commits, opening PRs, or posting review comments, read\n[Agent-authored Git and review activity](CONTRIBUTING.md#agent-authored-git-and-review-activity).\nAgent-authored commits and AI-generated PRs and comments each require their\nown disclosure; a PR-body disclosure alone does not cover later activity.\n\n## Other Contribution Guidance\n\nFor contribution or repository-workflow questions not covered above, or when\nthe applicable guidance is unclear, read [CONTRIBUTING.md](CONTRIBUTING.md)\nbefore acting.\n\n## Common Pitfalls\n\n- **Running tests against the wrong environment:** Run the suite inside this\n worktree's own virtualenv (`uv sync --extra test` then\n `.venv/bin/python -m pytest`). A bare `uv run pytest` can pick up an\n editable install from another worktree and fail to import new subpackages.\n","extensions/README.md":"# Spec Kit Extensions\n\nExtension system for [Spec Kit](https://github.com/github/spec-kit) - add new functionality without bloating the core framework.\n\n## Extension Catalogs\n\nSpec Kit provides two catalog files with different purposes:\n\n### Your Catalog (`catalog.json`)\n\n- **Purpose**: Default upstream catalog of extensions used by the Spec Kit CLI\n- **Default State**: Empty by design in the upstream project - you or your organization populate a fork/copy with extensions you trust\n- **Location (upstream)**: `extensions/catalog.json` in the GitHub-hosted spec-kit repo\n- **CLI Default**: The `specify extension` commands use the upstream catalog URL by default, unless overridden\n- **Org Catalog**: Point `SPECKIT_CATALOG_URL` at your organization's fork or hosted catalog JSON to use it instead of the upstream default\n- **Customization**: Copy entries from the community catalog into your org catalog, or add your own extensions directly\n\n**Example override:**\n```bash\n# Override the default upstream catalog with your organization's catalog\nexport SPECKIT_CATALOG_URL=\"https://your-org.com/spec-kit/catalog.json\"\nspecify extension search # Now uses your organization's catalog instead of the upstream default\n```\n\n### Community Reference Catalog (`catalog.community.json`)\n\n> [!NOTE]\n> Community extensions are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the extension code itself**. Review extension source code before installation and use at your own discretion.\n\n- **Purpose**: Browse available community-contributed extensions\n- **Status**: Active - contains extensions submitted by the community\n- **Location**: `extensions/catalog.community.json`\n- **Usage**: Reference catalog for discovering available extensions\n- **Submission**: Open to community contributions via [issue template](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml)\n\n**How It Works:**\n\n## Making Extensions Available\n\nYou control which extensions your team can discover and install:\n\n### Option 1: Curated Catalog (Recommended for Organizations)\n\nPopulate your `catalog.json` with approved extensions:\n\n1. **Discover** extensions from various sources:\n - Browse `catalog.community.json` for community extensions\n - Find private/internal extensions in your organization's repos\n - Discover extensions from trusted third parties\n2. **Review** extensions and choose which ones you want to make available\n3. **Add** those extension entries to your own `catalog.json`\n4. **Team members** can now discover and install them:\n - `specify extension search` shows your curated catalog\n - `specify extension add ` installs from your catalog\n\n**Benefits**: Full control over available extensions, team consistency, organizational approval workflow\n\n**Example**: Copy an entry from `catalog.community.json` to your `catalog.json`, then your team can discover and install it by name.\n\n### Option 2: Direct URLs (For Ad-hoc Use)\n\nSkip catalog curation - team members install directly using URLs:\n\n```bash\nspecify extension add --from https://github.com/org/spec-kit-ext/archive/refs/tags/v1.0.0.zip\n```\n\n**Benefits**: Quick for one-off testing or private extensions\n\n**Tradeoff**: Extensions installed this way won't appear in `specify extension search` for other team members unless you also add them to your `catalog.json`.\n\n## Available Community Extensions\n\n> [!NOTE]\n> Community extensions are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the extension code itself**. The Community Extensions website is also a third-party resource. Review extension source code before installation and use at your own discretion.\n\n🔍 **Browse and search community extensions on the [Community Extensions website](https://speckit-community.github.io/extensions/).**\n\nSee the [Community Extensions](https://github.github.io/spec-kit/community/extensions.html) page for the full list of available community-contributed extensions.\n\nFor the raw catalog data, see [`catalog.community.json`](catalog.community.json).\n\n\n## Adding Your Extension\n\n### Submission Process\n\nTo add your extension to the community catalog:\n\n1. **Prepare your extension** following the [Extension Development Guide](EXTENSION-DEVELOPMENT-GUIDE.md)\n2. **Create a GitHub release** for your extension\n3. **File an issue** using the [Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml) template with all required metadata\n4. **Wait for review** — a maintainer will review the submission, update the catalog, and close the issue\n\nSee the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) for detailed step-by-step instructions.\n\n### Submission Checklist\n\nBefore submitting, ensure:\n\n- ✅ Valid `extension.yml` manifest\n- ✅ Complete README with installation and usage instructions\n- ✅ LICENSE file included\n- ✅ GitHub release created with semantic version (e.g., v1.0.0)\n- ✅ Extension tested on a real project\n- ✅ All commands working as documented\n\n## Installing Extensions\nOnce extensions are available (either in your catalog or via direct URL), install them:\n\n```bash\n# From your curated catalog (by name)\nspecify extension search # See what's in your catalog\nspecify extension add # Install by name\n\n# Direct from URL (bypasses catalog)\nspecify extension add --from https://github.com///archive/refs/tags/.zip\n\n# List installed extensions\nspecify extension list\n```\n\nFor more information, see the [Extension User Guide](EXTENSION-USER-GUIDE.md).\n","extensions/agent-context/README.md":"# Coding Agent Context Extension\n\nThis bundled extension manages the **coding agent context/instruction file** (e.g. `CLAUDE.md`, `.github/copilot-instructions.md`, `AGENTS.md`, `GEMINI.md`, …) for the active integration.\n\nIt owns the lifecycle of the managed section delimited by the configurable start/end markers (defaults: `` / ``). For `.mdc` files, it also ensures the YAML frontmatter (the metadata block at the top of the file) contains `alwaysApply: true`. Otherwise, everything outside the managed section is untouched.\n\n> NOTE: Spec Kit itself never touches your agent context file. This extension is the only thing that does, and it's opt-in: install it if you want the block kept in sync, skip it if you'd rather manage that file yourself.\n\n## Why an extension?\n\nNot every Spec Kit user wants Spec Kit to write into the coding agent's context file. Keeping this behavior in a dedicated, **opt-in** extension lets users:\n\n- **Choose whether to install it at all** - `specify init` does **not** install it. Add it explicitly when you want Spec Kit to manage the agent context file; when it is absent, the file is never modified, and when it is disabled, its automatic hooks do not run.\n- **Customize the markers** by editing `.specify/extensions/agent-context/agent-context-config.yml` ([agent-context-config.yml](./agent-context-config.yml) in this repo) - the bundled scripts honor the `context_markers` value.\n- **Synchronize multiple agent anchors** by setting `context_files` when a project intentionally uses more than one coding agent context file, such as `AGENTS.md` and `CLAUDE.md`.\n- **Refresh on demand** by running the `speckit.agent-context.update` command in your agent, or automatically through the hooks declared in [extension.yml](./extension.yml) (`after_specify`, `after_plan`).\n\n## Installation\n\nTo install the extension, from the root of an initialized Spec Kit project, run:\n\n```bash\nspecify extension add agent-context\n```\n\n## Disabling\n\n```bash\nspecify extension disable agent-context\n\n# Re-enable it\nspecify extension enable agent-context\n```\n\nWhile this extension is disabled (or not installed), nothing in Spec Kit creates, updates, or removes the managed block - the `__CONTEXT_FILE__` placeholder in any template is left as-is, and the extension's own config is never read.\n\n## Commands\n\n| Command | Description |\n| ------------------------------ | --------------------------------------------------------------------------------- |\n| `speckit.agent-context.update` | Refresh the managed section in the agent context file with the current plan path. |\n\n> NOTE: The command ID above is canonical. Invoke it using the syntax for your integration: `/speckit.agent-context.update` for dot-command integrations; `/speckit-agent-context-update` for hyphen/skills integrations (including Forge and Cline); `$speckit-agent-context-update` for Codex or ZCode in skills mode; or `/skill:speckit-agent-context-update` for Kimi.\n\n## Configuration\n\nAll configuration flows through the extension's own config file at `.specify/extensions/agent-context/agent-context-config.yml` ([agent-context-config.yml](./agent-context-config.yml) in the repo).\n\n## Requirements\n\nThe bundled update scripts require **Python 3** with **PyYAML** for YAML/upsert processing (PowerShell can also use `ConvertFrom-Yaml` when available).\n\nPyYAML ships with the `specify` CLI and is normally available via the same `python3` interpreter. If a hook reports _\"PyYAML is required … not available in the current Python environment\"_, it means the system `python3` differs from the one used to install Spec Kit. To resolve, run:\n\n```bash\npip install pyyaml\n# or target the specific interpreter Spec Kit uses:\n/path/to/speckit-python -m pip install pyyaml\n```\n\n## Issues\n\nFor any other issues, please create an issue in the [official GitHub repo](https://github.com/github/spec-kit/issues).\n","extensions/assess/README.md":"# Idea Assessment Pipeline Extension\n\nA five-stage assessment pipeline for Spec Kit that turns **any idea** into a defensible **go / needs-clarification / kill** decision *before* it enters Spec-Driven Development. It is the missing **discovery track** that sits in front of the SDD **delivery track** (`specify → clarify → plan → tasks → analyze → implement`).\n\nDiscovery answers *\"is this worth building?\"* Delivery answers *\"how do we build it?\"* Only ideas that survive assessment hand off to `/speckit.specify`.\n\n## Overview\n\n`assess` runs inside an initialized Spec Kit project (it writes assessments under `.specify/assessments/`), but that project can be **completely empty of source code** — a freshly initialized project with no code works just as well as an established codebase. The input is just an idea: pasted text, a URL, or a ticket need no existing code, while a codebase pointer lets you assess an idea for code that already exists. Neither starting point is more \"correct\" than the other.\n\nEach idea lives in its own directory under `.specify/assessments//`, with one Markdown artifact per stage:\n\n```\n.specify/assessments//\n├── intake.md # speckit.assess.intake — capture the raw idea\n├── research.md # speckit.assess.research — gather (and challenge with) evidence\n├── problem.md # speckit.assess.define — define the problem, goals, metrics\n├── concept.md # speckit.assess.shape — shape solution options + appetite\n└── decision.md # speckit.assess.decide — go / needs-clarification / kill → handoff\n```\n\nThe pipeline is a **funnel**: most ideas should be killed or parked before `shape`. Killing an idea with a documented reason is a successful outcome, not a failure.\n\n```mermaid\nflowchart LR\n A[intake] --> R[research] --> D[define] --> S[shape] --> C{decide}\n C -->|go| SPEC[/speckit.specify/]\n C -->|kill| X[closed, recorded]\n C -.->|needs-clarification| F[refine named artifact in place]\n F -.->|then revise decision.md| C\n```\n\n## Commands\n\n| Command | Stage | Output |\n|---------|-------|--------|\n| `speckit.assess.intake` | Capture & normalize a raw idea (text, URL, ticket, or codebase pointer). | `intake.md` |\n| `speckit.assess.research` | Gather users/market/prior-art/data evidence — and evidence *against* the idea. | `research.md` |\n| `speckit.assess.define` | Define the problem: users, goals, non-goals, success metrics, cost of inaction. | `problem.md` |\n| `speckit.assess.shape` | Shape 2–3 concept-level options with appetite and trade-offs; recommend one (or none). | `concept.md` |\n| `speckit.assess.decide` | Score against criteria and render the verdict; hand `go` ideas to `/speckit.specify`. | `decision.md` |\n\nStages are meant to run in order but are not rigidly gated:\n\n- `define` is the minimum viable stage and can run directly on user input (intake/research optional).\n- `shape` requires `problem.md`.\n- `decide` requires `problem.md`; a `go` verdict expects `concept.md` (otherwise it is downgraded to `needs-clarification`).\n\n## Resolving clarifications\n\nThe normal process is sequential and each command usually runs **once**:\n\n```text\nintake → research → define → shape → decide\n```\n\nEach stage writes a Markdown artifact under `.specify/assessments//`. Those files stay editable. The commands keep their existing output templates: they do not rewrite an earlier artifact or perform that refinement themselves. `[NEEDS CLARIFICATION: …]` markers are gaps in the artifact, not a signal to regenerate the whole stage from scratch.\n\nResolve them by refining the existing file:\n\n1. **Edit the Markdown directly** (fill in the missing metric, owner, constraint, and so on), or\n2. **Ask the agent in free-form chat** to incorporate the missing information into that artifact.\n\nThen ask whether the new information clears the blocker and to update any downstream wording that depended on it. That includes `decision.md`: you can supply the missing facts and ask the agent to revise the scorecard, rationale, verdict, or handoff. That is artifact refinement, not command iteration.\n\nWhen you add evidence, keep the source and confidence tags the research stage already uses (`ASSUMPTION` vs cited claims). Do not invent citations.\n\nRerunning an earlier `speckit.assess.*` command is the exception (for example after a wrong slug or a discarded draft), not the default path for answering clarification markers.\n\n## Slug Conventions\n\nA *slug* is the per-idea directory name under `.specify/assessments/`. It is the handle all five commands share.\n\n- **User-provided**: normalized to lowercase kebab-case (e.g. `offline-mode`, `cut-onboarding-friction`). Preserved verbatim after normalization — no timestamps or numbers appended.\n- **Asked for**: in interactive use, `speckit.assess.intake` asks for a slug when none is supplied, suggesting a kebab-case default derived from the idea.\n- **Automated**: when no human is available, the agent generates a unique slug and never overwrites an existing assessment directory (appending `-2`, `-3`, … or a short date as needed).\n- **Reuse from context**: later stages reuse the slug reported earlier in the same session, confirmed by the presence of the assessment directory.\n\n## Installation\n\n```bash\nspecify extension add assess\n```\n\n## Disabling\n\n```bash\nspecify extension disable assess\nspecify extension enable assess\n```\n\n## Typical Flow\n\n```bash\n# 1. Capture an idea (pasted text, a URL, or \"assess this repo\")\n/speckit.assess.intake \"Let users work offline and sync when they reconnect\" slug=offline-mode\n\n# 2. Gather evidence — and reasons it might not be worth it\n/speckit.assess.research slug=offline-mode\n\n# 3. Define the actual problem\n/speckit.assess.define slug=offline-mode\n\n# 4. Shape 2–3 concept options with appetites\n/speckit.assess.shape slug=offline-mode\n\n# 5. Decide — go, clarify, or kill\n/speckit.assess.decide slug=offline-mode\n# → on \"go\", hand the decision.md handoff summary to /speckit.specify\n```\n\n## Handoff\n\n`assess` is a **standalone pipeline you enter deliberately** — it registers no lifecycle hooks and never inserts itself into `/speckit.specify`. The only coupling runs forward and by choice: a `go` verdict from `/speckit.assess.decide` hands its `decision.md` summary to `/speckit.specify`. Discovery and specification stay separate processes.\n\n## Guardrails\n\n- Only `speckit.assess.*` commands write, and only inside `.specify/assessments//`. **None of them modify source code** — solution design and implementation belong to the SDD lifecycle (`/speckit.specify` onward).\n- Web content fetched during `intake`/`research` is treated as untrusted data, governed by an explicit URL Trust Policy (allowlisted public sources fetched freely; unknown hosts prompted or skipped; loopback/RFC1918/metadata endpoints refused).\n- Evidence is never over-claimed: unsourced statements are tagged `ASSUMPTION`, and `research.md` always includes an *Evidence Against the Idea* section.\n- Verdicts are never over-claimed: a `go` requires a valid problem, `adequate`+ evidence (never weak/unknown), and a shaped concept; otherwise the honest verdict is `needs-clarification`.\n- Slugs are normalized to `[a-z0-9-]` and an empty result is rejected; before any read or write, each command also rejects symlinked path components and verifies the resolved path stays inside the project root — so an assessment can never escape `.specify/assessments/`, even in a crafted or cloned project.\n- No command overwrites an existing artifact without confirmation; in automated mode it refuses.\n\n## Relationship to Other Extensions\n\n`assess` is deliberately the **generic, role-neutral** discovery track — usable by a founder, PM, BA, engineer, or designer. Richer or more specialized pre-SDD flows in the community catalog (e.g. product-lifecycle orchestrators, technical-discovery, intake-normalization, brownfield onboarding) can layer on top of or feed into it; `assess` aims to be the minimal, opinionated funnel that ends cleanly at the `/speckit.specify` handoff.\n","extensions/bug/README.md":"# Bug Triage Workflow Extension\n\nA three-step bug triage workflow for Spec Kit: assess, fix, and validate. Each bug lives in its own directory under `.specify/bugs//`, with one Markdown report per stage.\n\n## Overview\n\nThis extension delivers an opinionated, repeatable bug workflow that any AI coding agent can drive:\n\n1. **Assess** — read a bug report (pasted text or a URL), judge whether it is a real bug, locate suspected code paths, and propose a remediation.\n2. **Fix** — apply the proposed remediation and record exactly what changed.\n3. **Test** — re-run the reproduction and any added tests, then record the verification result.\n\nThe three stages communicate through three Markdown files in a single per-bug directory:\n\n```\n.specify/bugs//\n├── assessment.md # written by speckit.bug.assess\n├── fix.md # written by speckit.bug.fix\n└── test.md # written by speckit.bug.test\n```\n\n## Commands\n\n| Command | Description | Output |\n|---------|-------------|--------|\n| `speckit.bug.assess` | Triages a bug report (pasted text or URL) against the codebase. | `.specify/bugs//assessment.md` |\n| `speckit.bug.fix` | Applies the remediation from the assessment. | `.specify/bugs//fix.md` |\n| `speckit.bug.test` | Validates the fix and records the verification report. | `.specify/bugs//test.md` |\n\n## Slug Conventions\n\nA *slug* is the per-bug directory name under `.specify/bugs/`. It is the only handle the three commands share.\n\n- **User-provided**: any shape the user wants, normalized to lowercase kebab-case (e.g. `login-timeout`, `cve-2026-001`, `oauth-redirect-500`). The slug is preserved verbatim after normalization — no timestamps or numbers are appended automatically.\n- **Asked for**: in interactive use, `speckit.bug.assess` asks for a slug when none is supplied, suggesting a kebab-case default derived from the bug summary.\n- **Automated**: when no human is available to answer, the agent generates a slug itself. The generated slug **MUST** produce a unique directory — if `.specify/bugs//` already exists, the agent appends the shortest disambiguating suffix needed (`-2`, `-3`, …) or a short date (`-20260605`). Existing bug directories are never overwritten.\n\n## Installation\n\n```bash\n# Install the bundled bug extension (no network required)\nspecify extension add bug\n```\n\n## Disabling\n\n```bash\n# Disable the bug extension\nspecify extension disable bug\n\n# Re-enable it\nspecify extension enable bug\n```\n\n## Typical Flow\n\n```bash\n# 1. Triage a bug from a pasted stack trace\n/speckit.bug.assess \"TypeError: cannot read properties of undefined (reading 'token') at /auth/callback\"\n\n# 2. Triage a bug from a GitHub issue URL\n/speckit.bug.assess https://github.com/example/repo/issues/1234 slug=callback-token\n\n# 3. Apply the proposed fix\n/speckit.bug.fix slug=callback-token\n\n# 4. Validate the fix\n/speckit.bug.test slug=callback-token\n```\n\n## Guardrails\n\n- `speckit.bug.assess` and `speckit.bug.test` **never modify source code**. They read the repository and write only inside `.specify/bugs//`.\n- `speckit.bug.fix` is the only command that edits source code, and it stays within the files listed in the assessment unless new evidence requires expanding scope (which is logged in `fix.md` under **Deviations from Assessment**).\n- None of the commands overwrite an existing report file without explicit confirmation; in automated mode they refuse and pick a new unique slug instead.\n- Verdicts and verification results are never over-claimed: a reproduction that was not actually performed is reported as `partial` or `not-run`, not `verified`.\n\n## Hooks\n\nThis extension registers no hooks of its own. The three commands are always invoked explicitly by the user, but expose lifecycle events for other extensions:\n\n| Command | Before event | After event |\n|---------|--------------|-------------|\n| `speckit.bug.assess` | `before_bug_assess` | `after_bug_assess` |\n| `speckit.bug.fix` | `before_bug_fix` | `after_bug_fix` |\n| `speckit.bug.test` | `before_bug_test` | `after_bug_test` |\n\nPre-hooks run after slug resolution and prerequisites, before execution. For assessment, the bug directory already exists before the pre-hook runs. Post-hooks run after `assessment.md`, `fix.md`, or `test.md` is written and before reporting completion. An unintelligible pasted report keeps the existing early stop: no assessment report, post-hooks, or completion report. Before-hooks run before ingestion, so they can already have run when a report is rejected; the prerequisite bug directory is not removed. Hooks are prompts run in the same session; they reuse the resolved `BUG_SLUG` and `BUG_DIR` (and, for post-hooks, the written report) from the conversation, and no variables are injected.\n\nFor example, an installed intake extension can register a hook in `.specify/extensions.yml`:\n\n```yaml\nhooks:\n before_bug_assess:\n - extension: intake\n command: speckit.intake.collect\n enabled: true\n optional: false\n description: Collect evidence in the resolved bug directory\n```\n\nMandatory hooks are invoked and awaited; optional hooks are presented for the user to run. Disabled hooks and hooks with non-empty conditions are skipped by the command templates. With no registered hooks, the workflow proceeds as before. See the [Extension API Reference](../EXTENSION-API-REFERENCE.md#hook-events) for the shared hook contract.\n","extensions/git/README.md":"# Git Branching Workflow Extension\n\nGit repository initialization, feature branch creation, numbering (sequential/timestamp), validation, remote detection, and auto-commit for Spec Kit.\n\n## Overview\n\nThis extension provides Git operations as an optional, self-contained module. It manages:\n\n- **Repository initialization** with configurable commit messages\n- **Feature branch creation** with sequential (`001-feature-name`) or timestamp (`20260319-143022-feature-name`) numbering and optional templates for branch namespaces\n- **Branch validation** to ensure branches follow naming conventions\n- **Git remote detection** for GitHub integration (e.g., issue creation)\n- **Auto-commit** after core commands (configurable per-command with custom messages, or Conventional Commit messages generated by the agent)\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `speckit.git.initialize` | Initialize a Git repository with a configurable commit message |\n| `speckit.git.feature` | Create a feature branch with sequential or timestamp numbering |\n| `speckit.git.validate` | Validate current branch follows feature branch naming conventions |\n| `speckit.git.remote` | Detect Git remote URL for GitHub integration |\n| `speckit.git.commit` | Auto-commit changes (configurable per-command enable/disable and messages) |\n\n## Hooks\n\n| Event | Command | Optional | Description |\n|-------|---------|----------|-------------|\n| `before_constitution` | `speckit.git.initialize` | No | Init git repo before constitution |\n| `before_specify` | `speckit.git.feature` | No | Create feature branch before specification |\n| `before_clarify` | `speckit.git.commit` | Yes | Commit outstanding changes before clarification |\n| `before_plan` | `speckit.git.commit` | Yes | Commit outstanding changes before planning |\n| `before_tasks` | `speckit.git.commit` | Yes | Commit outstanding changes before task generation |\n| `before_implement` | `speckit.git.commit` | Yes | Commit outstanding changes before implementation |\n| `before_checklist` | `speckit.git.commit` | Yes | Commit outstanding changes before checklist |\n| `before_analyze` | `speckit.git.commit` | Yes | Commit outstanding changes before analysis |\n| `before_taskstoissues` | `speckit.git.commit` | Yes | Commit outstanding changes before issue sync |\n| `after_constitution` | `speckit.git.commit` | Yes | Auto-commit after constitution update |\n| `after_specify` | `speckit.git.commit` | Yes | Auto-commit after specification |\n| `after_clarify` | `speckit.git.commit` | Yes | Auto-commit after clarification |\n| `after_plan` | `speckit.git.commit` | Yes | Auto-commit after planning |\n| `after_tasks` | `speckit.git.commit` | Yes | Auto-commit after task generation |\n| `after_implement` | `speckit.git.commit` | Yes | Auto-commit after implementation |\n| `after_checklist` | `speckit.git.commit` | Yes | Auto-commit after checklist |\n| `after_analyze` | `speckit.git.commit` | Yes | Auto-commit after analysis |\n| `after_taskstoissues` | `speckit.git.commit` | Yes | Auto-commit after issue sync |\n\n## Configuration\n\nConfiguration is stored in `.specify/extensions/git/git-config.yml`:\n\n```yaml\n# Branch numbering strategy: \"sequential\" or \"timestamp\"\nbranch_numbering: sequential\n\n# Optional branch name template. Leave empty for the default \"{number}-{slug}\".\n# Supported tokens: {author}, {app}, {number}, {slug}; {slug} must not appear\n# before {number}, and the final path segment must start with {number}-.\n# Example for monorepos: \"{author}/{app}/{number}-{slug}\"\nbranch_template: \"\"\n\n# Optional shorthand namespace. Leave empty to use branch_template/default behavior.\n# Example: \"features/{app}\" expands to \"features/{app}/{number}-{slug}\"\nbranch_prefix: \"\"\n\n# Custom commit message for git init\ninit_commit_message: \"[Spec Kit] Initial commit\"\n\n# Commit message style for auto-commit hooks: \"fixed\" (default) uses the\n# messages below; \"conventional\" asks the agent to generate a Conventional\n# Commit message (e.g. \"feat: add OAuth spec\") from the diff instead.\ncommit_style: fixed\n\n# Auto-commit per command (all disabled by default)\n# Example: enable auto-commit after specify\nauto_commit:\n default: false\n after_specify:\n enabled: true\n message: \"[Spec Kit] Add specification\"\n```\n\n`{author}` is derived from Git config and sanitized for branch names. `{app}` is derived from the Spec Kit init directory name. Custom templates must not put `{slug}` before `{number}`, and must put `{number}-` at the start of the final path segment so generated names remain valid feature branches. For a monorepo project at `apps/web/.specify/`, a template such as `{author}/{app}/{number}-{slug}` produces branches like `jdoe/web/008-guided-tour`.\n\nFor simple namespace-only customization, `branch_prefix` is also accepted as a shorthand and expands to `/{number}-{slug}`.\n\n## Installation\n\n```bash\n# Install the bundled git extension (no network required)\nspecify extension add git\n```\n\n## Disabling\n\n```bash\n# Disable the git extension (spec creation continues without branching)\nspecify extension disable git\n\n# Re-enable it\nspecify extension enable git\n```\n\n## Graceful Degradation\n\nWhen Git is not installed or the directory is not a Git repository:\n- Spec directories are still created under `specs/`\n- Branch creation is skipped with a warning\n- Branch validation is skipped with a warning\n- Remote detection returns empty results\n\n## Scripts\n\nThe extension bundles cross-platform scripts:\n\n- `scripts/bash/create-new-feature-branch.sh` — Bash implementation (branch creation only)\n- `scripts/bash/git-common.sh` — Shared Git utilities (Bash)\n- `scripts/powershell/create-new-feature-branch.ps1` — PowerShell implementation (branch creation only)\n- `scripts/powershell/git-common.ps1` — Shared Git utilities (PowerShell)\n","extensions/github/README.md":"# GitHub Integration Extension\n\nThis bundled, **opt-in** extension is the home for Spec Kit's GitHub *platform* functionality. Today it provides one command, `speckit.github.taskstoissues`, which turns a feature's `tasks.md` into dependency-ordered GitHub issues.\n\n> NOTE: `git` and `github` are deliberately separate domains. The [`git` extension](../git/README.md) owns local version-control workflow (feature branches, commits, remote detection); this extension owns interactions with the GitHub platform itself.\n\n## Why an extension?\n\nCreating GitHub issues is provider-specific project management, not part of the provider-neutral Spec-Driven Development lifecycle. Keeping it in a dedicated, opt-in extension lets users:\n\n- **Choose whether to install it at all** — `specify init` does **not** install it.\n- **Use a different issue tracker** without having to work around a GitHub-specific core command.\n- **Depend on a stable, namespaced command** from other extensions.\n\n## Installation\n\nFrom the root of an initialized Spec Kit project:\n\n```bash\nspecify extension add github\n```\n\nThe `generic` (bring your own agent) integration registers this command under\nits configured `--commands-dir` in both commands and skills layouts. Installing\n`github` creates `speckit.github.taskstoissues.md` in commands mode or\n`speckit-github-taskstoissues/SKILL.md` in skills mode. The core\n`speckit.taskstoissues` command is deprecated but remains available during migration.\nUse this extension's recommended command instead. See\n[integration-specific options](../../docs/integrations/cli.md#integration-specific-options).\n\n## Removal\n\n```bash\nspecify extension remove github\n```\n\n## Commands\n\n| Command | Description |\n| ------------------------------ | -------------------------------------------------------------------- |\n| `speckit.github.taskstoissues` | Recommended: convert tasks from `tasks.md` into dependency-ordered GitHub issues. |\n\n> NOTE: The command ID above is canonical. Invoke it using the syntax for your integration: `/speckit.github.taskstoissues` for dot-command integrations; `/speckit-github-taskstoissues` for slash-hyphen integrations (including Forge and Cline); `$speckit-github-taskstoissues` for Codex, ZCode, or Command Code in skills mode; or `/skill:speckit-github-taskstoissues` for Kimi.\n\n### What the command does\n\n1. Resolves the active feature and loads its `tasks.md` (via this extension's own `resolve-tasks` script — see [Scripts](#scripts)).\n2. Reads the Git remote and **stops unless it points at GitHub**.\n3. Lists existing repository issues — open *and* closed — and matches their titles against the task IDs in `tasks.md` (`\\bT\\d{3,}\\b`, so four-digit and longer IDs are handled).\n4. Creates issues titled `T001: ` only for task IDs that do not already have one, in the repository identified by the remote.\n\n## Hooks\n\nThis extension consumes the existing `before_taskstoissues` and `after_taskstoissues` hook points, which are read from `.specify/extensions.yml` at run time. The hook keys are unchanged from the core command, so hooks registered by other extensions — for example the `git` extension's auto-commit hooks — keep firing exactly as before.\n\n## Requirements\n\n- Spec Kit **0.12.17 or newer**. Extension-local `scripts/...` path rewriting arrived in\n 0.12.6, but auto-registered skills did not resolve `__SPECKIT_COMMAND_*__` references\n until 0.12.17. Earlier releases cannot render this command correctly in every supported\n layout, so `specify extension add github` refuses to install below 0.12.17.\n- A Git remote pointing at GitHub.\n- The **GitHub MCP server** available to your coding agent, providing the `list_issues` and `issue_write` tools.\n\n> NOTE: Agents without MCP support (for example the Pi Coding Agent out of the box) cannot run this command as intended.\n\n## Scripts\n\nThe extension ships its own feature-resolution script in all three supported runtimes, so it is self-contained and does not reach into core:\n\n| Runtime | Script |\n| ---------- | ---------------------------------------- |\n| Bash | `scripts/bash/resolve-tasks.sh` |\n| PowerShell | `scripts/powershell/resolve-tasks.ps1` |\n| Python | `scripts/python/resolve_tasks.py` |\n\nOnce installed they live under `.specify/extensions/github/scripts/`. The script is a trimmed twin of core's `check-prerequisites`: it resolves the project root and active feature directory, requires `plan.md` and `tasks.md`, and reports the design docs alongside them. It matches the invocation the core command makes (`--require-tasks --include-tasks`), so `spec.md` stays optional. By default, a `SPECIFY_FEATURE_DIRECTORY` override is persisted to `.specify/feature.json` so a later run without the variable resolves to the same feature. When `SPECIFY_FEATURE_NO_PERSIST=1` or `true`, the override still selects the feature for this run, but the script does not create or modify `feature.json`.\n\nPrerequisite errors name the Spec Kit command without assuming an integration's invocation syntax. Use the syntax described under [Commands](#commands) for your integration.\n\n## Migrating from the core `taskstoissues` command\n\nSpec Kit is moving GitHub issue tracking out of core in three stages:\n\n1. **Initial stage (completed)** — this extension shipped with the core `/speckit.taskstoissues` command still available.\n2. **Next (current stage)** — the replacement has been available for at least one release, so the core command is now deprecated. It displays a migration warning and continues its existing workflow. It does not install or enable the extension automatically or run the replacement command.\n3. **Later** — the core command will be removed in a future minor release.\n\nFor existing projects, upgrading the CLI alone does not refresh the generated\ncore command files. After upgrading the CLI, run this from the project root:\n\n```bash\nspecify integration upgrade \n```\n\nReplace `` with the installed integration key, or omit it to upgrade the\ndefault integration. This refreshes the core command with the deprecation\nwarning. If locally modified files block the upgrade, inspect those changes\nbefore deciding whether to overwrite them. See [Upgrade an Integration](../../docs/integrations/cli.md#upgrade-an-integration).\n\nTo migrate, install the extension and use the namespaced command instead:\n\n```bash\nspecify extension add github\n```\n\nThe `generic` integration supports this migration in both commands and skills\nlayouts under its configured `--commands-dir`. The core command remains\navailable during this deprecation period until the removal stage.\n\n| Deprecated core command | Recommended extension command |\n| ------------------------- | --------------------------------- |\n| `/speckit.taskstoissues` | `/speckit.github.taskstoissues` |\n\nApart 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.\n\n### Presets and dependent extensions\n\nBefore the core command is removed, audit references to `speckit.taskstoissues`\nin presets, extension prompts, workflow steps, handoffs, and project automation.\nFor GitHub issue conversion, use the canonical `speckit.github.taskstoissues`\ncommand ID and render it with the agent-specific syntax under [Commands](#commands).\nReplace `__SPECKIT_COMMAND_TASKSTOISSUES__` cross-command references with\n`__SPECKIT_COMMAND_GITHUB_TASKSTOISSUES__` where template rendering is supported.\nDocument `specify extension add github` as a setup prerequisite; the deprecation\nwarning does not install this dependency.\n\nIf an extension proposal or external dependency declaration uses\n`requires.commands: [speckit.taskstoissues]`, update its target to\n`speckit.github.taskstoissues`. `requires.commands` is not an enforced dependency\nfield in the current extension manifest API, so do not rely on that declaration\nto install or check the GitHub extension. Follow the supported requirements in\nthe [extension API reference](../EXTENSION-API-REFERENCE.md#extension-manifest).\n\nPreset command overrides are separate from command references: an override of\n`speckit.taskstoissues` does not automatically customize the namespaced GitHub\ncommand. Review and port any needed customization, then verify the installed\ncommand in a sample project before retiring the old override. A preset that\nuses another issue tracker should retain its own provider-specific workflow\nrather than redirecting it to the GitHub command. Existing overrides may also\nhide the core deprecation warning, so communicate the migration to their users.\n\nKeep the `before_taskstoissues` and `after_taskstoissues` hook keys unchanged;\nboth commands consume them. Only update a hook's command reference if it invokes\nthe deprecated command. Do not invoke both core and replacement commands for\nthe same conversion, since that also runs their hooks twice. Publish and test\nupdated preset/extension versions before the later core-removal release.\n","extensions/template/EXAMPLE-README.md":"# EXAMPLE: Extension README\n\nThis is an example of what your extension README should look like after customization.\n**Delete this file and replace README.md with content similar to this.**\n\n---\n\n# My Extension\n\n\n\nBrief description of what your extension does and why it's useful.\n\n## Features\n\n\n\n- Feature 1: Description\n- Feature 2: Description\n- Feature 3: Description\n\n## Installation\n\n```bash\n# Install from catalog\nspecify extension add my-extension\n\n# Or install from local development directory\nspecify extension add --dev /path/to/my-extension\n```\n\n## Configuration\n\n1. Create configuration file:\n\n ```bash\n cp .specify/extensions/my-extension/config-template.yml \\\n .specify/extensions/my-extension/my-extension-config.yml\n ```\n\n2. Edit configuration:\n\n ```bash\n vim .specify/extensions/my-extension/my-extension-config.yml\n ```\n\n3. Set required values:\n \n ```yaml\n connection:\n url: \"https://api.example.com\"\n api_key: \"your-api-key\"\n\n project:\n id: \"your-project-id\"\n ```\n\n## Usage\n\n\n\n### Command: example\n\nDescription of what this command does.\n\n```bash\n# In Claude Code\n> /speckit.my-extension.example\n```\n\n**Prerequisites**:\n\n- Prerequisite 1\n- Prerequisite 2\n\n**Output**:\n\n- What this command produces\n- Where results are saved\n\n## Configuration Reference\n\n\n\n### Connection Settings\n\n| Setting | Type | Required | Description |\n|---------|------|----------|-------------|\n| `connection.url` | string | Yes | API endpoint URL |\n| `connection.api_key` | string | Yes | API authentication key |\n\n### Project Settings\n\n| Setting | Type | Required | Description |\n|---------|------|----------|-------------|\n| `project.id` | string | Yes | Project identifier |\n| `project.workspace` | string | No | Workspace or organization |\n\n## Environment Variables\n\nOverride configuration with environment variables:\n\n```bash\n# Override connection settings\nexport SPECKIT_MY_EXTENSION_CONNECTION_URL=\"https://custom-api.com\"\nexport SPECKIT_MY_EXTENSION_CONNECTION_API_KEY=\"custom-key\"\n```\n\n## Examples\n\n\n\n### Example 1: Basic Workflow\n\n```bash\n# Step 1: Create specification\n> /speckit.spec\n\n# Step 2: Generate tasks\n> /speckit.tasks\n\n# Step 3: Use extension\n> /speckit.my-extension.example\n```\n\n## Troubleshooting\n\n\n\n### Issue: Configuration not found\n\n**Solution**: Create config from template (see Configuration section)\n\n### Issue: Command not available\n\n**Solutions**:\n\n1. Check extension is installed: `specify extension list`\n2. Restart AI agent\n3. Reinstall extension\n\n## License\n\nMIT License - see LICENSE file\n\n## Support\n\n- **Issues**: \n- **Spec Kit Docs**: \n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history.\n\n---\n\n*Extension Version: 1.0.0*\n*Spec Kit: >=0.1.0*\n","extensions/template/README.md":"# Extension Template\n\nStarter template for creating a Spec Kit extension.\n\n## Quick Start\n\n1. **Copy this template**:\n\n ```bash\n cp -r extensions/template my-extension\n cd my-extension\n ```\n\n2. **Customize `extension.yml`**:\n - Change extension ID, name, description\n - Update author and repository\n - Define your commands\n\n3. **Create commands**:\n - Add command files in `commands/` directory\n - Use Markdown format with YAML frontmatter\n\n4. **Create config template**:\n - Define configuration options\n - Document all settings\n\n5. **Write documentation**:\n - Update README.md with usage instructions\n - Add examples\n\n6. **Test locally**:\n\n ```bash\n cd /path/to/spec-kit-project\n specify extension add --dev /path/to/my-extension\n ```\n\n7. **Publish** (optional):\n - Create GitHub repository\n - Create release\n - Submit to catalog (see EXTENSION-PUBLISHING-GUIDE.md)\n\n## Files in This Template\n\n- `extension.yml` - Extension manifest (CUSTOMIZE THIS)\n- `config-template.yml` - Configuration template (CUSTOMIZE THIS)\n- `commands/example.md` - Example command (REPLACE THIS)\n- `README.md` - Extension documentation (REPLACE THIS)\n- `LICENSE` - MIT License (REVIEW THIS)\n- `CHANGELOG.md` - Version history (UPDATE THIS)\n- `.gitignore` - Git ignore rules\n\n## Customization Checklist\n\n- [ ] Update `extension.yml` with your extension details\n- [ ] Change extension ID to your extension name\n- [ ] Update author information\n- [ ] Define your commands\n- [ ] Create command files in `commands/`\n- [ ] Update config template\n- [ ] Write README with usage instructions\n- [ ] Add examples\n- [ ] Update LICENSE if needed\n- [ ] Test extension locally\n- [ ] Create git repository\n- [ ] Create first release\n\n## Need Help?\n\n- **Development Guide**: See EXTENSION-DEVELOPMENT-GUIDE.md\n- **API Reference**: See EXTENSION-API-REFERENCE.md\n- **Publishing Guide**: See EXTENSION-PUBLISHING-GUIDE.md\n- **User Guide**: See EXTENSION-USER-GUIDE.md\n\n## Template Version\n\n- Version: 1.0.0\n- Last Updated: 2026-01-28\n- Compatible with Spec Kit: >=0.1.0\n"},"files":{".github/skills/add-community-extension/SKILL.md":"---\nname: add-community-extension\ndescription: 'Add a community extension to the Spec Kit catalog from a GitHub issue submission. USE FOR: processing extension submission issues, validating catalog entries, updating catalog.community.json and docs/community/extensions.md, creating PRs. DO NOT USE FOR: creating new extensions from scratch, or first-party extension work.'\nargument-hint: 'GitHub issue URL or number for the extension submission'\n---\n\n# Add Community Extension\n\nProcess an extension submission issue and add or update it in the community catalog.\n\n## When to Use\n\n- A new `[Extension]` submission issue is filed\n- An existing extension submits an update issue (new version, changed metadata)\n- You need to add or update a community extension in `extensions/catalog.community.json` and `docs/community/extensions.md`\n\n## Procedure\n\n### 1. Fetch the submission issue\n\nRead the GitHub issue to extract all metadata:\n- Extension ID, name, version, description, author\n- Repository URL, download URL, homepage, documentation, changelog\n- License, required spec-kit version, optional tool dependencies\n- Number of commands and hooks\n- Tags\n\n### 2. Validate against publishing rules\n\nCheck **all** of the following (per `extensions/EXTENSION-PUBLISHING-GUIDE.md`):\n\n| Check | How |\n|-------|-----|\n| Repository exists and is public | Fetch the repository URL |\n| `extension.yml` manifest present | Confirm in repo file listing |\n| README.md present | Confirm in repo file listing |\n| LICENSE file present | Confirm in repo file listing |\n| GitHub release exists matching version | Check releases on the repo page |\n| Download URL is accessible | Verify it follows `archive/refs/tags/vX.Y.Z.zip` pattern and release exists |\n| Extension ID is lowercase-with-hyphens only | Regex: `^[a-z][a-z0-9-]*$` |\n| Version follows semver | Format: `X.Y.Z` |\n| Submission checklists are all checked | Confirm in issue body |\n\n### 3. Determine if this is an add or update\n\nSearch `extensions/catalog.community.json` for the extension ID.\n\n- **Not found** → this is a **new addition**. Proceed to step 4.\n- **Found** → this is an **update**. Proceed to step 4 but replace the existing entry in-place instead of inserting.\n\n### 4. Add or update `extensions/catalog.community.json`\n\n**New extension:** Insert the entry in **alphabetical order** by extension ID.\n\n**Update:** Replace the existing entry in-place. Update only the fields that changed (typically `version`, `download_url`, `description`, `provides`, `requires`, `tags`, `updated_at`). Preserve `created_at` and `downloads`/`stars` from the existing entry.\n\nUse the existing entries as the format template. Required fields:\n\n```json\n{\n \"\": {\n \"name\": \"\",\n \"id\": \"\",\n \"description\": \"\",\n \"author\": \"\",\n \"version\": \"\",\n \"download_url\": \"\",\n \"repository\": \"\",\n \"homepage\": \"\",\n \"documentation\": \"\",\n \"changelog\": \"\",\n \"license\": \"\",\n \"category\": \"\",\n \"effect\": \"\",\n \"requires\": {\n \"speckit_version\": \"\"\n },\n \"provides\": {\n \"commands\": ,\n \"hooks\": \n },\n \"tags\": [\"\", \"\"],\n \"verified\": false,\n \"downloads\": 0,\n \"stars\": 0,\n \"created_at\": \"T00:00:00Z\",\n \"updated_at\": \"T00:00:00Z\"\n }\n}\n```\n\n**Category** — free-form string; common values: `docs`, `code`, `process`, `integration`, `visibility`\n**Effect** — one of: `read-only`, `read-write`\n\nIf the extension has optional tool dependencies, add a `\"tools\"` array inside `\"requires\"`:\n\n```json\n\"tools\": [{ \"name\": \"\", \"required\": false }]\n```\n\nAlso update the top-level `\"updated_at\"` timestamp in the catalog.\n\nAfter editing, **validate the JSON** by running:\n\n```bash\npython3 -c \"import json; json.load(open('extensions/catalog.community.json')); print('Valid JSON')\"\n```\n\n### 5. Add or update `docs/community/extensions.md` community extensions table\n\n**New extension:** Insert a new row into the `# Community Extensions` table in **alphabetical order** by extension name.\n\n**Update:** Find the existing row and update the description or other changed fields in-place.\n\nDetermine the category and effect from the extension's behavior:\n\n```\n| | | `` | | []() |\n```\n\n**Category** — free-form; common values: `docs`, `code`, `process`, `integration`, `visibility`\n**Effect** — write canonical values `read-only` or `read-write` in `extension.yml` and `catalog.community.json`; use `Read-only`/`Read+Write` only for the docs table display\n\n### 6. Commit, push, and open PR\n\nUse `add-` for new extensions, `update-` for updates:\n\n```bash\n# New extension\ngit checkout -b add--extension\n\n# Update\ngit checkout -b update--extension\n```\n\n```bash\ngit add extensions/catalog.community.json docs/community/extensions.md\n\n# New extension\ngit commit -m \"Add extension to community catalog\n\nAdd extension submitted by @ to:\n- extensions/catalog.community.json (alphabetical order)\n- docs/community/extensions.md community extensions table\n\nCloses #\"\n\n# Update\ngit commit -m \"Update extension to v\n\nUpdate extension submitted by @:\n- extensions/catalog.community.json (version, download_url, etc.)\n- docs/community/extensions.md community extensions table\n\nCloses #\"\n\ngit push origin \n```\n\nThen create a PR to `upstream` (`github/spec-kit`) with:\n- **Title:** `Add extension to community catalog` (or `Update extension to v`)\n- **Body:** Include validation summary, `Closes #`, and `cc @`\n- **Head:** `:`\n- **Base:** `main`\n\n## Common Pitfalls\n\n- **Alphabetical order matters** — entries must be sorted by ID in the JSON and by name in the docs table.\n- **Don't forget the catalog `updated_at`** — the top-level timestamp in `catalog.community.json` must be refreshed.\n- **Validate JSON after editing** — a trailing comma or missing brace will break the catalog.\n- **Use `Closes` not `Fixes`** — `Closes #N` is the correct keyword for submission issues.\n- **Match the proposed entry but verify** — the issue may include a proposed JSON block, but always validate field values against the actual repository state.\n- **Preserve `created_at` on updates** — keep the original `created_at` value; only change `updated_at`.\n- **Preserve `downloads` and `stars` on updates** — these reflect usage metrics and must not be reset.\n",".github/skills/code-review/SKILL.md":"---\nname: code-review\ndescription: Reviews Spec Kit code changes for consistency with applicable design documents, positive and negative test coverage, regression evidence for bug fixes, and consistent repository terminology. Use when reviewing a diff or pull request. Do not use for implementing changes or posting GitHub review actions.\nargument-hint: 'Diff or pull request to review'\n---\n\n# Code Review\n\n1. Ensure each code change has test cases that verify what the code should do and what it should prevent.\n2. Ensure bug-fix pull requests include a regression test that demonstrates the bug was reproducible before the change and is fixed afterward; if the reviewer cannot run the comparison, use available evidence and state that limitation.\n3. Ensure wording changes use repository-consistent terms; exclude community-authored catalog content and its generated documentation from this check.\n4. Identify the affected domains and read the applicable documents in `design/` before evaluating architectural consistency. For CLI command changes, use `design/cli.md`; for agent integrations, use `design/integration.md`; for workflow step types, use `design/workflow-step.md`. Read other design documents when relevant, not every document for every PR.\n5. Check the changes against the applicable design requirements, including implementation boundaries, ownership, lifecycle, and delivery requirements. Reference the documents rather than duplicating their rules in this skill. Cite the document and section for each reported mismatch.\n6. Distinguish an unexplained design violation from an intentional design change. Evaluate the rationale and evidence for an intentional change; updating the design document alone does not establish that the implementation is justified.\n","AGENTS.md":"# AGENTS.md\n\n## About Spec Kit and Specify\n\n**GitHub Spec Kit** is a comprehensive toolkit for implementing Spec-Driven Development (SDD) - a methodology that emphasizes creating clear specifications before implementation. The toolkit includes templates, scripts, and workflows that guide development teams through a structured approach to building software.\n\n**Specify CLI** is the command-line interface that bootstraps projects with the Spec Kit framework. It sets up the necessary directory structures, templates, and AI agent integrations to support the Spec-Driven Development workflow.\n\nThe toolkit supports multiple AI coding assistants, allowing teams to use their preferred tools while maintaining consistent project structure and development practices.\n\n## Adding or Updating CLI Commands\n\nBefore adding, updating, or reorganizing Specify CLI commands, read\n[Shared Command Application Architecture](design/shared.md) and\n[Specify CLI Command Architecture](design/cli.md). They define the shared\noperation boundary, command-module naming, private phases, nested command\ngroups, registration ownership, and mirrored tests.\n\n## Adding or Updating MCP Commands\n\nBefore adding or changing MCP tools for Specify commands, read\n[Shared Command Application Architecture](design/shared.md) and\n[Specify MCP Command Architecture](design/mcp.md). They define the shared\noperation boundary, typed contracts, explicit inventory, side-effect metadata,\nthe local stdio protocol boundary, and mirrored tests.\n\n## Adding or Updating Agent Integrations\n\nBefore adding or changing AI agent integrations, read\n[Agent Integration Design](design/integration.md). It covers\ndelivery routes, output formats, registration, and install/uninstall ownership.\n\n## Adding or Updating Workflow Steps\n\nBefore adding or changing workflow step types, read\n[Workflow Step Design](design/workflow-step.md). It covers registration,\nvalidation, execution, resume, and installed step packages.\n\n## Testing Executable Behavior\n\nBefore changing code or configuration that runs or controls execution without\nan LLM, read\n[Testing deterministic behavior](CONTRIBUTING.md#testing-deterministic-behavior).\nBehavioral changes need positive and negative coverage; bug fixes need\nbefore-and-after regression evidence.\n\n## PowerShell Compatibility\n\nAll PowerShell scripts in the repository and all generated PowerShell\nfunctionality MUST target Windows PowerShell 5.1, the version included with\nWindows. When adding or changing PowerShell code, use only syntax, cmdlets,\nparameters, and .NET APIs available in Windows PowerShell 5.1. Account for\nencoding and other runtime differences, preserve the required behavioral\nparity with Bash and Python implementations, and provide Windows PowerShell\n5.1 validation evidence for behavioral changes.\n\n## Branches and Agent Contributions\n\nWhen creating a branch, follow [Branch naming](CONTRIBUTING.md#branch-naming).\nBefore authoring commits, opening PRs, or posting review comments, read\n[Agent-authored Git and review activity](CONTRIBUTING.md#agent-authored-git-and-review-activity).\nAgent-authored commits and AI-generated PRs and comments each require their\nown disclosure; a PR-body disclosure alone does not cover later activity.\n\n## Other Contribution Guidance\n\nFor contribution or repository-workflow questions not covered above, or when\nthe applicable guidance is unclear, read [CONTRIBUTING.md](CONTRIBUTING.md)\nbefore acting.\n\n## Common Pitfalls\n\n- **Running tests against the wrong environment:** Run the suite inside this\n worktree's own virtualenv (`uv sync --extra test` then\n `.venv/bin/python -m pytest`). A bare `uv run pytest` can pick up an\n editable install from another worktree and fail to import new subpackages.\n","extensions/README.md":"# Spec Kit Extensions\n\nExtension system for [Spec Kit](https://github.com/github/spec-kit) - add new functionality without bloating the core framework.\n\n## Extension Catalogs\n\nSpec Kit provides two catalog files with different purposes:\n\n### Your Catalog (`catalog.json`)\n\n- **Purpose**: Default upstream catalog of extensions used by the Spec Kit CLI\n- **Default State**: Empty by design in the upstream project - you or your organization populate a fork/copy with extensions you trust\n- **Location (upstream)**: `extensions/catalog.json` in the GitHub-hosted spec-kit repo\n- **CLI Default**: The `specify extension` commands use the upstream catalog URL by default, unless overridden\n- **Org Catalog**: Point `SPECKIT_CATALOG_URL` at your organization's fork or hosted catalog JSON to use it instead of the upstream default\n- **Customization**: Copy entries from the community catalog into your org catalog, or add your own extensions directly\n\n**Example override:**\n```bash\n# Override the default upstream catalog with your organization's catalog\nexport SPECKIT_CATALOG_URL=\"https://your-org.com/spec-kit/catalog.json\"\nspecify extension search # Now uses your organization's catalog instead of the upstream default\n```\n\n### Community Reference Catalog (`catalog.community.json`)\n\n> [!NOTE]\n> Community extensions are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the extension code itself**. Review extension source code before installation and use at your own discretion.\n\n- **Purpose**: Browse available community-contributed extensions\n- **Status**: Active - contains extensions submitted by the community\n- **Location**: `extensions/catalog.community.json`\n- **Usage**: Reference catalog for discovering available extensions\n- **Submission**: Open to community contributions via [issue template](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml)\n\n**How It Works:**\n\n## Making Extensions Available\n\nYou control which extensions your team can discover and install:\n\n### Option 1: Curated Catalog (Recommended for Organizations)\n\nPopulate your `catalog.json` with approved extensions:\n\n1. **Discover** extensions from various sources:\n - Browse `catalog.community.json` for community extensions\n - Find private/internal extensions in your organization's repos\n - Discover extensions from trusted third parties\n2. **Review** extensions and choose which ones you want to make available\n3. **Add** those extension entries to your own `catalog.json`\n4. **Team members** can now discover and install them:\n - `specify extension search` shows your curated catalog\n - `specify extension add ` installs from your catalog\n\n**Benefits**: Full control over available extensions, team consistency, organizational approval workflow\n\n**Example**: Copy an entry from `catalog.community.json` to your `catalog.json`, then your team can discover and install it by name.\n\n### Option 2: Direct URLs (For Ad-hoc Use)\n\nSkip catalog curation - team members install directly using URLs:\n\n```bash\nspecify extension add --from https://github.com/org/spec-kit-ext/archive/refs/tags/v1.0.0.zip\n```\n\n**Benefits**: Quick for one-off testing or private extensions\n\n**Tradeoff**: Extensions installed this way won't appear in `specify extension search` for other team members unless you also add them to your `catalog.json`.\n\n## Available Community Extensions\n\n> [!NOTE]\n> Community extensions are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the extension code itself**. The Community Extensions website is also a third-party resource. Review extension source code before installation and use at your own discretion.\n\n🔍 **Browse and search community extensions on the [Community Extensions website](https://speckit-community.github.io/extensions/).**\n\nSee the [Community Extensions](https://github.github.io/spec-kit/community/extensions.html) page for the full list of available community-contributed extensions.\n\nFor the raw catalog data, see [`catalog.community.json`](catalog.community.json).\n\n\n## Adding Your Extension\n\n### Submission Process\n\nTo add your extension to the community catalog:\n\n1. **Prepare your extension** following the [Extension Development Guide](EXTENSION-DEVELOPMENT-GUIDE.md)\n2. **Create a GitHub release** for your extension\n3. **File an issue** using the [Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml) template with all required metadata\n4. **Wait for review** — a maintainer will review the submission, update the catalog, and close the issue\n\nSee the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) for detailed step-by-step instructions.\n\n### Submission Checklist\n\nBefore submitting, ensure:\n\n- ✅ Valid `extension.yml` manifest\n- ✅ Complete README with installation and usage instructions\n- ✅ LICENSE file included\n- ✅ GitHub release created with semantic version (e.g., v1.0.0)\n- ✅ Extension tested on a real project\n- ✅ All commands working as documented\n\n## Installing Extensions\nOnce extensions are available (either in your catalog or via direct URL), install them:\n\n```bash\n# From your curated catalog (by name)\nspecify extension search # See what's in your catalog\nspecify extension add # Install by name\n\n# Direct from URL (bypasses catalog)\nspecify extension add --from https://github.com///archive/refs/tags/.zip\n\n# List installed extensions\nspecify extension list\n```\n\nFor more information, see the [Extension User Guide](EXTENSION-USER-GUIDE.md).\n","extensions/agent-context/README.md":"# Coding Agent Context Extension\n\nThis bundled extension manages the **coding agent context/instruction file** (e.g. `CLAUDE.md`, `.github/copilot-instructions.md`, `AGENTS.md`, `GEMINI.md`, …) for the active integration.\n\nIt owns the lifecycle of the managed section delimited by the configurable start/end markers (defaults: `` / ``). For `.mdc` files, it also ensures the YAML frontmatter (the metadata block at the top of the file) contains `alwaysApply: true`. Otherwise, everything outside the managed section is untouched.\n\n> NOTE: Spec Kit itself never touches your agent context file. This extension is the only thing that does, and it's opt-in: install it if you want the block kept in sync, skip it if you'd rather manage that file yourself.\n\n## Why an extension?\n\nNot every Spec Kit user wants Spec Kit to write into the coding agent's context file. Keeping this behavior in a dedicated, **opt-in** extension lets users:\n\n- **Choose whether to install it at all** - `specify init` does **not** install it. Add it explicitly when you want Spec Kit to manage the agent context file; when it is absent, the file is never modified, and when it is disabled, its automatic hooks do not run.\n- **Customize the markers** by editing `.specify/extensions/agent-context/agent-context-config.yml` ([agent-context-config.yml](./agent-context-config.yml) in this repo) - the bundled scripts honor the `context_markers` value.\n- **Synchronize multiple agent anchors** by setting `context_files` when a project intentionally uses more than one coding agent context file, such as `AGENTS.md` and `CLAUDE.md`.\n- **Refresh on demand** by running the `speckit.agent-context.update` command in your agent, or automatically through the hooks declared in [extension.yml](./extension.yml) (`after_specify`, `after_plan`).\n\n## Installation\n\nTo install the extension, from the root of an initialized Spec Kit project, run:\n\n```bash\nspecify extension add agent-context\n```\n\n## Disabling\n\n```bash\nspecify extension disable agent-context\n\n# Re-enable it\nspecify extension enable agent-context\n```\n\nWhile this extension is disabled (or not installed), nothing in Spec Kit creates, updates, or removes the managed block - the `__CONTEXT_FILE__` placeholder in any template is left as-is, and the extension's own config is never read.\n\n## Commands\n\n| Command | Description |\n| ------------------------------ | --------------------------------------------------------------------------------- |\n| `speckit.agent-context.update` | Refresh the managed section in the agent context file with the current plan path. |\n\n> NOTE: The command ID above is canonical. Invoke it using the syntax for your integration: `/speckit.agent-context.update` for dot-command integrations; `/speckit-agent-context-update` for hyphen/skills integrations (including Forge and Cline); `$speckit-agent-context-update` for Codex or ZCode in skills mode; or `/skill:speckit-agent-context-update` for Kimi.\n\n## Configuration\n\nAll configuration flows through the extension's own config file at `.specify/extensions/agent-context/agent-context-config.yml` ([agent-context-config.yml](./agent-context-config.yml) in the repo).\n\n## Requirements\n\nThe bundled update scripts require **Python 3** with **PyYAML** for YAML/upsert processing (PowerShell can also use `ConvertFrom-Yaml` when available).\n\nPyYAML ships with the `specify` CLI and is normally available via the same `python3` interpreter. If a hook reports _\"PyYAML is required … not available in the current Python environment\"_, it means the system `python3` differs from the one used to install Spec Kit. To resolve, run:\n\n```bash\npip install pyyaml\n# or target the specific interpreter Spec Kit uses:\n/path/to/speckit-python -m pip install pyyaml\n```\n\n## Issues\n\nFor any other issues, please create an issue in the [official GitHub repo](https://github.com/github/spec-kit/issues).\n","extensions/assess/README.md":"# Idea Assessment Pipeline Extension\n\nA five-stage assessment pipeline for Spec Kit that turns **any idea** into a defensible **go / needs-clarification / kill** decision *before* it enters Spec-Driven Development. It is the missing **discovery track** that sits in front of the SDD **delivery track** (`specify → clarify → plan → tasks → analyze → implement`).\n\nDiscovery answers *\"is this worth building?\"* Delivery answers *\"how do we build it?\"* Only ideas that survive assessment hand off to `/speckit.specify`.\n\n## Overview\n\n`assess` runs inside an initialized Spec Kit project (it writes assessments under `.specify/assessments/`), but that project can be **completely empty of source code** — a freshly initialized project with no code works just as well as an established codebase. The input is just an idea: pasted text, a URL, or a ticket need no existing code, while a codebase pointer lets you assess an idea for code that already exists. Neither starting point is more \"correct\" than the other.\n\nEach idea lives in its own directory under `.specify/assessments//`, with one Markdown artifact per stage:\n\n```\n.specify/assessments//\n├── intake.md # speckit.assess.intake — capture the raw idea\n├── research.md # speckit.assess.research — gather (and challenge with) evidence\n├── problem.md # speckit.assess.define — define the problem, goals, metrics\n├── concept.md # speckit.assess.shape — shape solution options + appetite\n└── decision.md # speckit.assess.decide — go / needs-clarification / kill → handoff\n```\n\nThe pipeline is a **funnel**: most ideas should be killed or parked before `shape`. Killing an idea with a documented reason is a successful outcome, not a failure.\n\n```mermaid\nflowchart LR\n A[intake] --> R[research] --> D[define] --> S[shape] --> C{decide}\n C -->|go| SPEC[/speckit.specify/]\n C -->|kill| X[closed, recorded]\n C -.->|needs-clarification| F[refine named artifact in place]\n F -.->|then revise decision.md| C\n```\n\n## Commands\n\n| Command | Stage | Output |\n|---------|-------|--------|\n| `speckit.assess.intake` | Capture & normalize a raw idea (text, URL, ticket, or codebase pointer). | `intake.md` |\n| `speckit.assess.research` | Gather users/market/prior-art/data evidence — and evidence *against* the idea. | `research.md` |\n| `speckit.assess.define` | Define the problem: users, goals, non-goals, success metrics, cost of inaction. | `problem.md` |\n| `speckit.assess.shape` | Shape 2–3 concept-level options with appetite and trade-offs; recommend one (or none). | `concept.md` |\n| `speckit.assess.decide` | Score against criteria and render the verdict; hand `go` ideas to `/speckit.specify`. | `decision.md` |\n\nStages are meant to run in order but are not rigidly gated:\n\n- `define` is the minimum viable stage and can run directly on user input (intake/research optional).\n- `shape` requires `problem.md`.\n- `decide` requires `problem.md`; a `go` verdict expects `concept.md` (otherwise it is downgraded to `needs-clarification`).\n\n## Resolving clarifications\n\nThe normal process is sequential and each command usually runs **once**:\n\n```text\nintake → research → define → shape → decide\n```\n\nEach stage writes a Markdown artifact under `.specify/assessments//`. Those files stay editable. The commands keep their existing output templates: they do not rewrite an earlier artifact or perform that refinement themselves. `[NEEDS CLARIFICATION: …]` markers are gaps in the artifact, not a signal to regenerate the whole stage from scratch.\n\nResolve them by refining the existing file:\n\n1. **Edit the Markdown directly** (fill in the missing metric, owner, constraint, and so on), or\n2. **Ask the agent in free-form chat** to incorporate the missing information into that artifact.\n\nThen ask whether the new information clears the blocker and to update any downstream wording that depended on it. That includes `decision.md`: you can supply the missing facts and ask the agent to revise the scorecard, rationale, verdict, or handoff. That is artifact refinement, not command iteration.\n\nWhen you add evidence, keep the source and confidence tags the research stage already uses (`ASSUMPTION` vs cited claims). Do not invent citations.\n\nRerunning an earlier `speckit.assess.*` command is the exception (for example after a wrong slug or a discarded draft), not the default path for answering clarification markers.\n\n## Slug Conventions\n\nA *slug* is the per-idea directory name under `.specify/assessments/`. It is the handle all five commands share.\n\n- **User-provided**: normalized to lowercase kebab-case (e.g. `offline-mode`, `cut-onboarding-friction`). Preserved verbatim after normalization — no timestamps or numbers appended.\n- **Asked for**: in interactive use, `speckit.assess.intake` asks for a slug when none is supplied, suggesting a kebab-case default derived from the idea.\n- **Automated**: when no human is available, the agent generates a unique slug and never overwrites an existing assessment directory (appending `-2`, `-3`, … or a short date as needed).\n- **Reuse from context**: later stages reuse the slug reported earlier in the same session, confirmed by the presence of the assessment directory.\n\n## Installation\n\n```bash\nspecify extension add assess\n```\n\n## Disabling\n\n```bash\nspecify extension disable assess\nspecify extension enable assess\n```\n\n## Typical Flow\n\n```bash\n# 1. Capture an idea (pasted text, a URL, or \"assess this repo\")\n/speckit.assess.intake \"Let users work offline and sync when they reconnect\" slug=offline-mode\n\n# 2. Gather evidence — and reasons it might not be worth it\n/speckit.assess.research slug=offline-mode\n\n# 3. Define the actual problem\n/speckit.assess.define slug=offline-mode\n\n# 4. Shape 2–3 concept options with appetites\n/speckit.assess.shape slug=offline-mode\n\n# 5. Decide — go, clarify, or kill\n/speckit.assess.decide slug=offline-mode\n# → on \"go\", hand the decision.md handoff summary to /speckit.specify\n```\n\n## Handoff\n\n`assess` is a **standalone pipeline you enter deliberately** — it registers no lifecycle hooks and never inserts itself into `/speckit.specify`. The only coupling runs forward and by choice: a `go` verdict from `/speckit.assess.decide` hands its `decision.md` summary to `/speckit.specify`. Discovery and specification stay separate processes.\n\n## Guardrails\n\n- Only `speckit.assess.*` commands write, and only inside `.specify/assessments//`. **None of them modify source code** — solution design and implementation belong to the SDD lifecycle (`/speckit.specify` onward).\n- Web content fetched during `intake`/`research` is treated as untrusted data, governed by an explicit URL Trust Policy (allowlisted public sources fetched freely; unknown hosts prompted or skipped; loopback/RFC1918/metadata endpoints refused).\n- Evidence is never over-claimed: unsourced statements are tagged `ASSUMPTION`, and `research.md` always includes an *Evidence Against the Idea* section.\n- Verdicts are never over-claimed: a `go` requires a valid problem, `adequate`+ evidence (never weak/unknown), and a shaped concept; otherwise the honest verdict is `needs-clarification`.\n- Slugs are normalized to `[a-z0-9-]` and an empty result is rejected; before any read or write, each command also rejects symlinked path components and verifies the resolved path stays inside the project root — so an assessment can never escape `.specify/assessments/`, even in a crafted or cloned project.\n- No command overwrites an existing artifact without confirmation; in automated mode it refuses.\n\n## Relationship to Other Extensions\n\n`assess` is deliberately the **generic, role-neutral** discovery track — usable by a founder, PM, BA, engineer, or designer. Richer or more specialized pre-SDD flows in the community catalog (e.g. product-lifecycle orchestrators, technical-discovery, intake-normalization, brownfield onboarding) can layer on top of or feed into it; `assess` aims to be the minimal, opinionated funnel that ends cleanly at the `/speckit.specify` handoff.\n","extensions/bug/README.md":"# Bug Triage Workflow Extension\n\nA three-step bug triage workflow for Spec Kit: assess, fix, and validate. Each bug lives in its own directory under `.specify/bugs//`, with one Markdown report per stage.\n\n## Overview\n\nThis extension delivers an opinionated, repeatable bug workflow that any AI coding agent can drive:\n\n1. **Assess** — read a bug report (pasted text or a URL), judge whether it is a real bug, locate suspected code paths, and propose a remediation.\n2. **Fix** — apply the proposed remediation and record exactly what changed.\n3. **Test** — re-run the reproduction and any added tests, then record the verification result.\n\nThe three stages communicate through three Markdown files in a single per-bug directory:\n\n```\n.specify/bugs//\n├── assessment.md # written by speckit.bug.assess\n├── fix.md # written by speckit.bug.fix\n└── test.md # written by speckit.bug.test\n```\n\n## Commands\n\n| Command | Description | Output |\n|---------|-------------|--------|\n| `speckit.bug.assess` | Triages a bug report (pasted text or URL) against the codebase. | `.specify/bugs//assessment.md` |\n| `speckit.bug.fix` | Applies the remediation from the assessment. | `.specify/bugs//fix.md` |\n| `speckit.bug.test` | Validates the fix and records the verification report. | `.specify/bugs//test.md` |\n\n## Slug Conventions\n\nA *slug* is the per-bug directory name under `.specify/bugs/`. It is the only handle the three commands share.\n\n- **User-provided**: any shape the user wants, normalized to lowercase kebab-case (e.g. `login-timeout`, `cve-2026-001`, `oauth-redirect-500`). The slug is preserved verbatim after normalization — no timestamps or numbers are appended automatically.\n- **Asked for**: in interactive use, `speckit.bug.assess` asks for a slug when none is supplied, suggesting a kebab-case default derived from the bug summary.\n- **Automated**: when no human is available to answer, the agent generates a slug itself. The generated slug **MUST** produce a unique directory — if `.specify/bugs//` already exists, the agent appends the shortest disambiguating suffix needed (`-2`, `-3`, …) or a short date (`-20260605`). Existing bug directories are never overwritten.\n\n## Installation\n\n```bash\n# Install the bundled bug extension (no network required)\nspecify extension add bug\n```\n\n## Disabling\n\n```bash\n# Disable the bug extension\nspecify extension disable bug\n\n# Re-enable it\nspecify extension enable bug\n```\n\n## Typical Flow\n\n```bash\n# 1. Triage a bug from a pasted stack trace\n/speckit.bug.assess \"TypeError: cannot read properties of undefined (reading 'token') at /auth/callback\"\n\n# 2. Triage a bug from a GitHub issue URL\n/speckit.bug.assess https://github.com/example/repo/issues/1234 slug=callback-token\n\n# 3. Apply the proposed fix\n/speckit.bug.fix slug=callback-token\n\n# 4. Validate the fix\n/speckit.bug.test slug=callback-token\n```\n\n## Guardrails\n\n- `speckit.bug.assess` and `speckit.bug.test` **never modify source code**. They read the repository and write only inside `.specify/bugs//`.\n- `speckit.bug.fix` is the only command that edits source code, and it stays within the files listed in the assessment unless new evidence requires expanding scope (which is logged in `fix.md` under **Deviations from Assessment**).\n- None of the commands overwrite an existing report file without explicit confirmation; in automated mode they refuse and pick a new unique slug instead.\n- Verdicts and verification results are never over-claimed: a reproduction that was not actually performed is reported as `partial` or `not-run`, not `verified`.\n\n## Hooks\n\nThis extension registers no hooks of its own. The three commands are always invoked explicitly by the user, but expose lifecycle events for other extensions:\n\n| Command | Before event | After event |\n|---------|--------------|-------------|\n| `speckit.bug.assess` | `before_bug_assess` | `after_bug_assess` |\n| `speckit.bug.fix` | `before_bug_fix` | `after_bug_fix` |\n| `speckit.bug.test` | `before_bug_test` | `after_bug_test` |\n\nPre-hooks run after slug resolution and prerequisites, before execution. For assessment, the bug directory already exists before the pre-hook runs. Post-hooks run after `assessment.md`, `fix.md`, or `test.md` is written and before reporting completion. An unintelligible pasted report keeps the existing early stop: no assessment report, post-hooks, or completion report. Before-hooks run before ingestion, so they can already have run when a report is rejected; the prerequisite bug directory is not removed. Hooks are prompts run in the same session; they reuse the resolved `BUG_SLUG` and `BUG_DIR` (and, for post-hooks, the written report) from the conversation, and no variables are injected.\n\nFor example, an installed intake extension can register a hook in `.specify/extensions.yml`:\n\n```yaml\nhooks:\n before_bug_assess:\n - extension: intake\n command: speckit.intake.collect\n enabled: true\n optional: false\n description: Collect evidence in the resolved bug directory\n```\n\nMandatory hooks are invoked and awaited; optional hooks are presented for the user to run. Disabled hooks and hooks with non-empty conditions are skipped by the command templates. With no registered hooks, the workflow proceeds as before. See the [Extension API Reference](../EXTENSION-API-REFERENCE.md#hook-events) for the shared hook contract.\n","extensions/git/README.md":"# Git Branching Workflow Extension\n\nGit repository initialization, feature branch creation, numbering (sequential/timestamp), validation, remote detection, and auto-commit for Spec Kit.\n\n## Overview\n\nThis extension provides Git operations as an optional, self-contained module. It manages:\n\n- **Repository initialization** with configurable commit messages\n- **Feature branch creation** with sequential (`001-feature-name`) or timestamp (`20260319-143022-feature-name`) numbering and optional templates for branch namespaces\n- **Branch validation** to ensure branches follow naming conventions\n- **Git remote detection** for GitHub integration (e.g., issue creation)\n- **Auto-commit** after core commands (configurable per-command with custom messages, or Conventional Commit messages generated by the agent)\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `speckit.git.initialize` | Initialize a Git repository with a configurable commit message |\n| `speckit.git.feature` | Create a feature branch with sequential or timestamp numbering |\n| `speckit.git.validate` | Validate current branch follows feature branch naming conventions |\n| `speckit.git.remote` | Detect Git remote URL for GitHub integration |\n| `speckit.git.commit` | Auto-commit changes (configurable per-command enable/disable and messages) |\n\n## Hooks\n\n| Event | Command | Optional | Description |\n|-------|---------|----------|-------------|\n| `before_constitution` | `speckit.git.initialize` | No | Init git repo before constitution |\n| `before_specify` | `speckit.git.feature` | No | Create feature branch before specification |\n| `before_clarify` | `speckit.git.commit` | Yes | Commit outstanding changes before clarification |\n| `before_plan` | `speckit.git.commit` | Yes | Commit outstanding changes before planning |\n| `before_tasks` | `speckit.git.commit` | Yes | Commit outstanding changes before task generation |\n| `before_implement` | `speckit.git.commit` | Yes | Commit outstanding changes before implementation |\n| `before_checklist` | `speckit.git.commit` | Yes | Commit outstanding changes before checklist |\n| `before_analyze` | `speckit.git.commit` | Yes | Commit outstanding changes before analysis |\n| `before_taskstoissues` | `speckit.git.commit` | Yes | Commit outstanding changes before issue sync |\n| `after_constitution` | `speckit.git.commit` | Yes | Auto-commit after constitution update |\n| `after_specify` | `speckit.git.commit` | Yes | Auto-commit after specification |\n| `after_clarify` | `speckit.git.commit` | Yes | Auto-commit after clarification |\n| `after_plan` | `speckit.git.commit` | Yes | Auto-commit after planning |\n| `after_tasks` | `speckit.git.commit` | Yes | Auto-commit after task generation |\n| `after_implement` | `speckit.git.commit` | Yes | Auto-commit after implementation |\n| `after_checklist` | `speckit.git.commit` | Yes | Auto-commit after checklist |\n| `after_analyze` | `speckit.git.commit` | Yes | Auto-commit after analysis |\n| `after_taskstoissues` | `speckit.git.commit` | Yes | Auto-commit after issue sync |\n\n## Configuration\n\nConfiguration is stored in `.specify/extensions/git/git-config.yml`:\n\n```yaml\n# Branch numbering strategy: \"sequential\" or \"timestamp\"\nbranch_numbering: sequential\n\n# Optional branch name template. Leave empty for the default \"{number}-{slug}\".\n# Supported tokens: {author}, {app}, {number}, {slug}; {slug} must not appear\n# before {number}, and the final path segment must start with {number}-.\n# Example for monorepos: \"{author}/{app}/{number}-{slug}\"\nbranch_template: \"\"\n\n# Optional shorthand namespace. Leave empty to use branch_template/default behavior.\n# Example: \"features/{app}\" expands to \"features/{app}/{number}-{slug}\"\nbranch_prefix: \"\"\n\n# Custom commit message for git init\ninit_commit_message: \"[Spec Kit] Initial commit\"\n\n# Commit message style for auto-commit hooks: \"fixed\" (default) uses the\n# messages below; \"conventional\" asks the agent to generate a Conventional\n# Commit message (e.g. \"feat: add OAuth spec\") from the diff instead.\ncommit_style: fixed\n\n# Auto-commit per command (all disabled by default)\n# Example: enable auto-commit after specify\nauto_commit:\n default: false\n after_specify:\n enabled: true\n message: \"[Spec Kit] Add specification\"\n```\n\n`{author}` is derived from Git config and sanitized for branch names. `{app}` is derived from the Spec Kit init directory name. Custom templates must not put `{slug}` before `{number}`, and must put `{number}-` at the start of the final path segment so generated names remain valid feature branches. For a monorepo project at `apps/web/.specify/`, a template such as `{author}/{app}/{number}-{slug}` produces branches like `jdoe/web/008-guided-tour`.\n\nFor simple namespace-only customization, `branch_prefix` is also accepted as a shorthand and expands to `/{number}-{slug}`.\n\n## Installation\n\n```bash\n# Install the bundled git extension (no network required)\nspecify extension add git\n```\n\n## Disabling\n\n```bash\n# Disable the git extension (spec creation continues without branching)\nspecify extension disable git\n\n# Re-enable it\nspecify extension enable git\n```\n\n## Graceful Degradation\n\nWhen Git is not installed or the directory is not a Git repository:\n- Spec directories are still created under `specs/`\n- Branch creation is skipped with a warning\n- Branch validation is skipped with a warning\n- Remote detection returns empty results\n\n## Scripts\n\nThe extension bundles cross-platform scripts:\n\n- `scripts/bash/create-new-feature-branch.sh` — Bash implementation (branch creation only)\n- `scripts/bash/git-common.sh` — Shared Git utilities (Bash)\n- `scripts/powershell/create-new-feature-branch.ps1` — PowerShell implementation (branch creation only)\n- `scripts/powershell/git-common.ps1` — Shared Git utilities (PowerShell)\n","extensions/github/README.md":"# GitHub Integration Extension\n\nThis bundled, **opt-in** extension is the home for Spec Kit's GitHub *platform* functionality. Today it provides one command, `speckit.github.taskstoissues`, which turns a feature's `tasks.md` into dependency-ordered GitHub issues.\n\n> NOTE: `git` and `github` are deliberately separate domains. The [`git` extension](../git/README.md) owns local version-control workflow (feature branches, commits, remote detection); this extension owns interactions with the GitHub platform itself.\n\n## Why an extension?\n\nCreating GitHub issues is provider-specific project management, not part of the provider-neutral Spec-Driven Development lifecycle. Keeping it in a dedicated, opt-in extension lets users:\n\n- **Choose whether to install it at all** — `specify init` does **not** install it.\n- **Use a different issue tracker** without having to work around a GitHub-specific core command.\n- **Depend on a stable, namespaced command** from other extensions.\n\n## Installation\n\nFrom the root of an initialized Spec Kit project:\n\n```bash\nspecify extension add github\n```\n\nThe `generic` (bring your own agent) integration registers this command under\nits configured `--commands-dir` in both commands and skills layouts. Installing\n`github` creates `speckit.github.taskstoissues.md` in commands mode or\n`speckit-github-taskstoissues/SKILL.md` in skills mode. The core\n`speckit.taskstoissues` command is deprecated but remains available during migration.\nUse this extension's recommended command instead. See\n[integration-specific options](../../docs/integrations/cli.md#integration-specific-options).\n\n## Removal\n\n```bash\nspecify extension remove github\n```\n\n## Commands\n\n| Command | Description |\n| ------------------------------ | -------------------------------------------------------------------- |\n| `speckit.github.taskstoissues` | Recommended: convert tasks from `tasks.md` into dependency-ordered GitHub issues. |\n\n> NOTE: The command ID above is canonical. Invoke it using the syntax for your integration: `/speckit.github.taskstoissues` for dot-command integrations; `/speckit-github-taskstoissues` for slash-hyphen integrations (including Forge and Cline); `$speckit-github-taskstoissues` for Codex, ZCode, or Command Code in skills mode; or `/skill:speckit-github-taskstoissues` for Kimi.\n\n### What the command does\n\n1. Resolves the active feature and loads its `tasks.md` (via this extension's own `resolve-tasks` script — see [Scripts](#scripts)).\n2. Reads the Git remote and **stops unless it points at GitHub**.\n3. Lists existing repository issues — open *and* closed — and matches their titles against the task IDs in `tasks.md` (`\\bT\\d{3,}\\b`, so four-digit and longer IDs are handled).\n4. Creates issues titled `T001: ` only for task IDs that do not already have one, in the repository identified by the remote.\n\n## Hooks\n\nThis extension consumes the existing `before_taskstoissues` and `after_taskstoissues` hook points, which are read from `.specify/extensions.yml` at run time. The hook keys are unchanged from the core command, so hooks registered by other extensions — for example the `git` extension's auto-commit hooks — keep firing exactly as before.\n\n## Requirements\n\n- Spec Kit **0.12.17 or newer**. Extension-local `scripts/...` path rewriting arrived in\n 0.12.6, but auto-registered skills did not resolve `__SPECKIT_COMMAND_*__` references\n until 0.12.17. Earlier releases cannot render this command correctly in every supported\n layout, so `specify extension add github` refuses to install below 0.12.17.\n- A Git remote pointing at GitHub.\n- The **GitHub MCP server** available to your coding agent, providing the `list_issues` and `issue_write` tools.\n\n> NOTE: Agents without MCP support (for example the Pi Coding Agent out of the box) cannot run this command as intended.\n\n## Scripts\n\nThe extension ships its own feature-resolution script in all three supported runtimes, so it is self-contained and does not reach into core:\n\n| Runtime | Script |\n| ---------- | ---------------------------------------- |\n| Bash | `scripts/bash/resolve-tasks.sh` |\n| PowerShell | `scripts/powershell/resolve-tasks.ps1` |\n| Python | `scripts/python/resolve_tasks.py` |\n\nOnce installed they live under `.specify/extensions/github/scripts/`. The script is a trimmed twin of core's `check-prerequisites`: it resolves the project root and active feature directory, requires `plan.md` and `tasks.md`, and reports the design docs alongside them. It matches the invocation the core command makes (`--require-tasks --include-tasks`), so `spec.md` stays optional. By default, a `SPECIFY_FEATURE_DIRECTORY` override is persisted to `.specify/feature.json` so a later run without the variable resolves to the same feature. When `SPECIFY_FEATURE_NO_PERSIST=1` or `true`, the override still selects the feature for this run, but the script does not create or modify `feature.json`.\n\nPrerequisite errors name the Spec Kit command without assuming an integration's invocation syntax. Use the syntax described under [Commands](#commands) for your integration.\n\n## Migrating from the core `taskstoissues` command\n\nSpec Kit is moving GitHub issue tracking out of core in three stages:\n\n1. **Initial stage (completed)** — this extension shipped with the core `/speckit.taskstoissues` command still available.\n2. **Next (current stage)** — the replacement has been available for at least one release, so the core command is now deprecated. It displays a migration warning and continues its existing workflow. It does not install or enable the extension automatically or run the replacement command.\n3. **Later** — the core command will be removed in a future minor release.\n\nFor existing projects, upgrading the CLI alone does not refresh the generated\ncore command files. After upgrading the CLI, run this from the project root:\n\n```bash\nspecify integration upgrade \n```\n\nReplace `` with the installed integration key, or omit it to upgrade the\ndefault integration. This refreshes the core command with the deprecation\nwarning. If locally modified files block the upgrade, inspect those changes\nbefore deciding whether to overwrite them. See [Upgrade an Integration](../../docs/integrations/cli.md#upgrade-an-integration).\n\nTo migrate, install the extension and use the namespaced command instead:\n\n```bash\nspecify extension add github\n```\n\nThe `generic` integration supports this migration in both commands and skills\nlayouts under its configured `--commands-dir`. The core command remains\navailable during this deprecation period until the removal stage.\n\n| Deprecated core command | Recommended extension command |\n| ------------------------- | --------------------------------- |\n| `/speckit.taskstoissues` | `/speckit.github.taskstoissues` |\n\nApart 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.\n\n### Presets and dependent extensions\n\nBefore the core command is removed, audit references to `speckit.taskstoissues`\nin presets, extension prompts, workflow steps, handoffs, and project automation.\nFor GitHub issue conversion, use the canonical `speckit.github.taskstoissues`\ncommand ID and render it with the agent-specific syntax under [Commands](#commands).\nReplace `__SPECKIT_COMMAND_TASKSTOISSUES__` cross-command references with\n`__SPECKIT_COMMAND_GITHUB_TASKSTOISSUES__` where template rendering is supported.\nDocument `specify extension add github` as a setup prerequisite; the deprecation\nwarning does not install this dependency.\n\nIf an extension proposal or external dependency declaration uses\n`requires.commands: [speckit.taskstoissues]`, update its target to\n`speckit.github.taskstoissues`. `requires.commands` is not an enforced dependency\nfield in the current extension manifest API, so do not rely on that declaration\nto install or check the GitHub extension. Follow the supported requirements in\nthe [extension API reference](../EXTENSION-API-REFERENCE.md#extension-manifest).\n\nPreset command overrides are separate from command references: an override of\n`speckit.taskstoissues` does not automatically customize the namespaced GitHub\ncommand. Review and port any needed customization, then verify the installed\ncommand in a sample project before retiring the old override. A preset that\nuses another issue tracker should retain its own provider-specific workflow\nrather than redirecting it to the GitHub command. Existing overrides may also\nhide the core deprecation warning, so communicate the migration to their users.\n\nKeep the `before_taskstoissues` and `after_taskstoissues` hook keys unchanged;\nboth commands consume them. Only update a hook's command reference if it invokes\nthe deprecated command. Do not invoke both core and replacement commands for\nthe same conversion, since that also runs their hooks twice. Publish and test\nupdated preset/extension versions before the later core-removal release.\n","extensions/template/EXAMPLE-README.md":"# EXAMPLE: Extension README\n\nThis is an example of what your extension README should look like after customization.\n**Delete this file and replace README.md with content similar to this.**\n\n---\n\n# My Extension\n\n\n\nBrief description of what your extension does and why it's useful.\n\n## Features\n\n\n\n- Feature 1: Description\n- Feature 2: Description\n- Feature 3: Description\n\n## Installation\n\n```bash\n# Install from catalog\nspecify extension add my-extension\n\n# Or install from local development directory\nspecify extension add --dev /path/to/my-extension\n```\n\n## Configuration\n\n1. Create configuration file:\n\n ```bash\n cp .specify/extensions/my-extension/config-template.yml \\\n .specify/extensions/my-extension/my-extension-config.yml\n ```\n\n2. Edit configuration:\n\n ```bash\n vim .specify/extensions/my-extension/my-extension-config.yml\n ```\n\n3. Set required values:\n \n ```yaml\n connection:\n url: \"https://api.example.com\"\n api_key: \"your-api-key\"\n\n project:\n id: \"your-project-id\"\n ```\n\n## Usage\n\n\n\n### Command: example\n\nDescription of what this command does.\n\n```bash\n# In Claude Code\n> /speckit.my-extension.example\n```\n\n**Prerequisites**:\n\n- Prerequisite 1\n- Prerequisite 2\n\n**Output**:\n\n- What this command produces\n- Where results are saved\n\n## Configuration Reference\n\n\n\n### Connection Settings\n\n| Setting | Type | Required | Description |\n|---------|------|----------|-------------|\n| `connection.url` | string | Yes | API endpoint URL |\n| `connection.api_key` | string | Yes | API authentication key |\n\n### Project Settings\n\n| Setting | Type | Required | Description |\n|---------|------|----------|-------------|\n| `project.id` | string | Yes | Project identifier |\n| `project.workspace` | string | No | Workspace or organization |\n\n## Environment Variables\n\nOverride configuration with environment variables:\n\n```bash\n# Override connection settings\nexport SPECKIT_MY_EXTENSION_CONNECTION_URL=\"https://custom-api.com\"\nexport SPECKIT_MY_EXTENSION_CONNECTION_API_KEY=\"custom-key\"\n```\n\n## Examples\n\n\n\n### Example 1: Basic Workflow\n\n```bash\n# Step 1: Create specification\n> /speckit.spec\n\n# Step 2: Generate tasks\n> /speckit.tasks\n\n# Step 3: Use extension\n> /speckit.my-extension.example\n```\n\n## Troubleshooting\n\n\n\n### Issue: Configuration not found\n\n**Solution**: Create config from template (see Configuration section)\n\n### Issue: Command not available\n\n**Solutions**:\n\n1. Check extension is installed: `specify extension list`\n2. Restart AI agent\n3. Reinstall extension\n\n## License\n\nMIT License - see LICENSE file\n\n## Support\n\n- **Issues**: \n- **Spec Kit Docs**: \n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history.\n\n---\n\n*Extension Version: 1.0.0*\n*Spec Kit: >=0.1.0*\n","extensions/template/README.md":"# Extension Template\n\nStarter template for creating a Spec Kit extension.\n\n## Quick Start\n\n1. **Copy this template**:\n\n ```bash\n cp -r extensions/template my-extension\n cd my-extension\n ```\n\n2. **Customize `extension.yml`**:\n - Change extension ID, name, description\n - Update author and repository\n - Define your commands\n\n3. **Create commands**:\n - Add command files in `commands/` directory\n - Use Markdown format with YAML frontmatter\n\n4. **Create config template**:\n - Define configuration options\n - Document all settings\n\n5. **Write documentation**:\n - Update README.md with usage instructions\n - Add examples\n\n6. **Test locally**:\n\n ```bash\n cd /path/to/spec-kit-project\n specify extension add --dev /path/to/my-extension\n ```\n\n7. **Publish** (optional):\n - Create GitHub repository\n - Create release\n - Submit to catalog (see EXTENSION-PUBLISHING-GUIDE.md)\n\n## Files in This Template\n\n- `extension.yml` - Extension manifest (CUSTOMIZE THIS)\n- `config-template.yml` - Configuration template (CUSTOMIZE THIS)\n- `commands/example.md` - Example command (REPLACE THIS)\n- `README.md` - Extension documentation (REPLACE THIS)\n- `LICENSE` - MIT License (REVIEW THIS)\n- `CHANGELOG.md` - Version history (UPDATE THIS)\n- `.gitignore` - Git ignore rules\n\n## Customization Checklist\n\n- [ ] Update `extension.yml` with your extension details\n- [ ] Change extension ID to your extension name\n- [ ] Update author information\n- [ ] Define your commands\n- [ ] Create command files in `commands/`\n- [ ] Update config template\n- [ ] Write README with usage instructions\n- [ ] Add examples\n- [ ] Update LICENSE if needed\n- [ ] Test extension locally\n- [ ] Create git repository\n- [ ] Create first release\n\n## Need Help?\n\n- **Development Guide**: See EXTENSION-DEVELOPMENT-GUIDE.md\n- **API Reference**: See EXTENSION-API-REFERENCE.md\n- **Publishing Guide**: See EXTENSION-PUBLISHING-GUIDE.md\n- **User Guide**: See EXTENSION-USER-GUIDE.md\n\n## Template Version\n\n- Version: 1.0.0\n- Last Updated: 2026-01-28\n- Compatible with Spec Kit: >=0.1.0\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/github/spec-kit/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# AGENTS.md\n\n## About Spec Kit and Specify\n\n**GitHub Spec Kit** is a comprehensive toolkit for implementing Spec-Driven Development (SDD) - a methodology that emphasizes creating clear specifications before implementation. The toolkit includes templates, scripts, and workflows that guide development teams through a structured approach to building software.\n\n**Specify CLI** is the command-line interface that bootstraps projects with the Spec Kit framework. It sets up the necessary directory structures, templates, and AI agent integrations to support the Spec-Driven Development workflow.\n\nThe toolkit supports multiple AI coding assistants, allowing teams to use their preferred tools while maintaining consistent project structure and development practices.\n\n## Adding or Updating CLI Commands\n\nBefore adding, updating, or reorganizing Specify CLI commands, read\n[Shared Command Application Architecture](design/shared.md) and\n[Specify CLI Command Architecture](design/cli.md). They define the shared\noperation boundary, command-module naming, private phases, nested command\ngroups, registration ownership, and mirrored tests.\n\n## Adding or Updating MCP Commands\n\nBefore adding or changing MCP tools for Specify commands, read\n[Shared Command Application Architecture](design/shared.md) and\n[Specify MCP Command Architecture](design/mcp.md). They define the shared\noperation boundary, typed contracts, explicit inventory, side-effect metadata,\nthe local stdio protocol boundary, and mirrored tests.\n\n## Adding or Updating Agent Integrations\n\nBefore adding or changing AI agent integrations, read\n[Agent Integration Design](design/integration.md). It covers\ndelivery routes, output formats, registration, and install/uninstall ownership.\n\n## Adding or Updating Workflow Steps\n\nBefore adding or changing workflow step types, read\n[Workflow Step Design](design/workflow-step.md). It covers registration,\nvalidation, execution, resume, and installed step packages.\n\n## Testing Executable Behavior\n\nBefore changing code or configuration that runs or controls execution without\nan LLM, read\n[Testing deterministic behavior](CONTRIBUTING.md#testing-deterministic-behavior).\nBehavioral changes need positive and negative coverage; bug fixes need\nbefore-and-after regression evidence.\n\n## PowerShell Compatibility\n\nAll PowerShell scripts in the repository and all generated PowerShell\nfunctionality MUST target Windows PowerShell 5.1, the version included with\nWindows. When adding or changing PowerShell code, use only syntax, cmdlets,\nparameters, and .NET APIs available in Windows PowerShell 5.1. Account for\nencoding and other runtime differences, preserve the required behavioral\nparity with Bash and Python implementations, and provide Windows PowerShell\n5.1 validation evidence for behavioral changes.\n\n## Branches and Agent Contributions\n\nWhen creating a branch, follow [Branch naming](CONTRIBUTING.md#branch-naming).\nBefore authoring commits, opening PRs, or posting review comments, read\n[Agent-authored Git and review activity](CONTRIBUTING.md#agent-authored-git-and-review-activity).\nAgent-authored commits and AI-generated PRs and comments each require their\nown disclosure; a PR-body disclosure alone does not cover later activity.\n\n## Other Contribution Guidance\n\nFor contribution or repository-workflow questions not covered above, or when\nthe applicable guidance is unclear, read [CONTRIBUTING.md](CONTRIBUTING.md)\nbefore acting.\n\n## Common Pitfalls\n\n- **Running tests against the wrong environment:** Run the suite inside this\n worktree's own virtualenv (`uv sync --extra test` then\n `.venv/bin/python -m pytest`). A bare `uv run pytest` can pick up an\n editable install from another worktree and fail to import new subpackages.\n","isInternal":false,"tokens":729,"sizeBytes":3747},{"name":"SKILL.md","path":".github/skills/add-community-extension/SKILL.md","rawUrl":"https://raw.githubusercontent.com/github/spec-kit/HEAD/.github/skills/add-community-extension/SKILL.md","title":"add-community-extension","category":"anthropic-skill","format":"markdown","content":"---\nname: add-community-extension\ndescription: 'Add a community extension to the Spec Kit catalog from a GitHub issue submission. USE FOR: processing extension submission issues, validating catalog entries, updating catalog.community.json and docs/community/extensions.md, creating PRs. DO NOT USE FOR: creating new extensions from scratch, or first-party extension work.'\nargument-hint: 'GitHub issue URL or number for the extension submission'\n---\n\n# Add Community Extension\n\nProcess an extension submission issue and add or update it in the community catalog.\n\n## When to Use\n\n- A new `[Extension]` submission issue is filed\n- An existing extension submits an update issue (new version, changed metadata)\n- You need to add or update a community extension in `extensions/catalog.community.json` and `docs/community/extensions.md`\n\n## Procedure\n\n### 1. Fetch the submission issue\n\nRead the GitHub issue to extract all metadata:\n- Extension ID, name, version, description, author\n- Repository URL, download URL, homepage, documentation, changelog\n- License, required spec-kit version, optional tool dependencies\n- Number of commands and hooks\n- Tags\n\n### 2. Validate against publishing rules\n\nCheck **all** of the following (per `extensions/EXTENSION-PUBLISHING-GUIDE.md`):\n\n| Check | How |\n|-------|-----|\n| Repository exists and is public | Fetch the repository URL |\n| `extension.yml` manifest present | Confirm in repo file listing |\n| README.md present | Confirm in repo file listing |\n| LICENSE file present | Confirm in repo file listing |\n| GitHub release exists matching version | Check releases on the repo page |\n| Download URL is accessible | Verify it follows `archive/refs/tags/vX.Y.Z.zip` pattern and release exists |\n| Extension ID is lowercase-with-hyphens only | Regex: `^[a-z][a-z0-9-]*$` |\n| Version follows semver | Format: `X.Y.Z` |\n| Submission checklists are all checked | Confirm in issue body |\n\n### 3. Determine if this is an add or update\n\nSearch `extensions/catalog.community.json` for the extension ID.\n\n- **Not found** → this is a **new addition**. Proceed to step 4.\n- **Found** → this is an **update**. Proceed to step 4 but replace the existing entry in-place instead of inserting.\n\n### 4. Add or update `extensions/catalog.community.json`\n\n**New extension:** Insert the entry in **alphabetical order** by extension ID.\n\n**Update:** Replace the existing entry in-place. Update only the fields that changed (typically `version`, `download_url`, `description`, `provides`, `requires`, `tags`, `updated_at`). Preserve `created_at` and `downloads`/`stars` from the existing entry.\n\nUse the existing entries as the format template. Required fields:\n\n```json\n{\n \"\": {\n \"name\": \"\",\n \"id\": \"\",\n \"description\": \"\",\n \"author\": \"\",\n \"version\": \"\",\n \"download_url\": \"\",\n \"repository\": \"\",\n \"homepage\": \"\",\n \"documentation\": \"\",\n \"changelog\": \"\",\n \"license\": \"\",\n \"category\": \"\",\n \"effect\": \"\",\n \"requires\": {\n \"speckit_version\": \"\"\n },\n \"provides\": {\n \"commands\": ,\n \"hooks\": \n },\n \"tags\": [\"\", \"\"],\n \"verified\": false,\n \"downloads\": 0,\n \"stars\": 0,\n \"created_at\": \"T00:00:00Z\",\n \"updated_at\": \"T00:00:00Z\"\n }\n}\n```\n\n**Category** — free-form string; common values: `docs`, `code`, `process`, `integration`, `visibility`\n**Effect** — one of: `read-only`, `read-write`\n\nIf the extension has optional tool dependencies, add a `\"tools\"` array inside `\"requires\"`:\n\n```json\n\"tools\": [{ \"name\": \"\", \"required\": false }]\n```\n\nAlso update the top-level `\"updated_at\"` timestamp in the catalog.\n\nAfter editing, **validate the JSON** by running:\n\n```bash\npython3 -c \"import json; json.load(open('extensions/catalog.community.json')); print('Valid JSON')\"\n```\n\n### 5. Add or update `docs/community/extensions.md` community extensions table\n\n**New extension:** Insert a new row into the `# Community Extensions` table in **alphabetical order** by extension name.\n\n**Update:** Find the existing row and update the description or other changed fields in-place.\n\nDetermine the category and effect from the extension's behavior:\n\n```\n| | | `` | | []() |\n```\n\n**Category** — free-form; common values: `docs`, `code`, `process`, `integration`, `visibility`\n**Effect** — write canonical values `read-only` or `read-write` in `extension.yml` and `catalog.community.json`; use `Read-only`/`Read+Write` only for the docs table display\n\n### 6. Commit, push, and open PR\n\nUse `add-` for new extensions, `update-` for updates:\n\n```bash\n# New extension\ngit checkout -b add--extension\n\n# Update\ngit checkout -b update--extension\n```\n\n```bash\ngit add extensions/catalog.community.json docs/community/extensions.md\n\n# New extension\ngit commit -m \"Add extension to community catalog\n\nAdd extension submitted by @ to:\n- extensions/catalog.community.json (alphabetical order)\n- docs/community/extensions.md community extensions table\n\nCloses #\"\n\n# Update\ngit commit -m \"Update extension to v\n\nUpdate extension submitted by @:\n- extensions/catalog.community.json (version, download_url, etc.)\n- docs/community/extensions.md community extensions table\n\nCloses #\"\n\ngit push origin \n```\n\nThen create a PR to `upstream` (`github/spec-kit`) with:\n- **Title:** `Add extension to community catalog` (or `Update extension to v`)\n- **Body:** Include validation summary, `Closes #`, and `cc @`\n- **Head:** `:`\n- **Base:** `main`\n\n## Common Pitfalls\n\n- **Alphabetical order matters** — entries must be sorted by ID in the JSON and by name in the docs table.\n- **Don't forget the catalog `updated_at`** — the top-level timestamp in `catalog.community.json` must be refreshed.\n- **Validate JSON after editing** — a trailing comma or missing brace will break the catalog.\n- **Use `Closes` not `Fixes`** — `Closes #N` is the correct keyword for submission issues.\n- **Match the proposed entry but verify** — the issue may include a proposed JSON block, but always validate field values against the actual repository state.\n- **Preserve `created_at` on updates** — keep the original `created_at` value; only change `updated_at`.\n- **Preserve `downloads` and `stars` on updates** — these reflect usage metrics and must not be reset.\n","frontmatter":{"name":"add-community-extension","description":"Add a community extension to the Spec Kit catalog from a GitHub issue submission. USE FOR: processing extension submission issues, validating catalog entries, updating catalog.community.json and docs/community/extensions.md, creating PRs. DO NOT USE FOR: creating new extensions from scratch, or first-party extension work.","argument-hint":"GitHub issue URL or number for the extension submission"},"isInternal":false,"tokens":1593,"sizeBytes":6678},{"name":"SKILL.md","path":".github/skills/code-review/SKILL.md","rawUrl":"https://raw.githubusercontent.com/github/spec-kit/HEAD/.github/skills/code-review/SKILL.md","title":"code-review","category":"anthropic-skill","format":"markdown","content":"---\nname: code-review\ndescription: Reviews Spec Kit code changes for consistency with applicable design documents, positive and negative test coverage, regression evidence for bug fixes, and consistent repository terminology. Use when reviewing a diff or pull request. Do not use for implementing changes or posting GitHub review actions.\nargument-hint: 'Diff or pull request to review'\n---\n\n# Code Review\n\n1. Ensure each code change has test cases that verify what the code should do and what it should prevent.\n2. Ensure bug-fix pull requests include a regression test that demonstrates the bug was reproducible before the change and is fixed afterward; if the reviewer cannot run the comparison, use available evidence and state that limitation.\n3. Ensure wording changes use repository-consistent terms; exclude community-authored catalog content and its generated documentation from this check.\n4. Identify the affected domains and read the applicable documents in `design/` before evaluating architectural consistency. For CLI command changes, use `design/cli.md`; for agent integrations, use `design/integration.md`; for workflow step types, use `design/workflow-step.md`. Read other design documents when relevant, not every document for every PR.\n5. Check the changes against the applicable design requirements, including implementation boundaries, ownership, lifecycle, and delivery requirements. Reference the documents rather than duplicating their rules in this skill. Cite the document and section for each reported mismatch.\n6. Distinguish an unexplained design violation from an intentional design change. Evaluate the rationale and evidence for an intentional change; updating the design document alone does not establish that the implementation is justified.\n","frontmatter":{"name":"code-review","description":"Reviews Spec Kit code changes for consistency with applicable design documents, positive and negative test coverage, regression evidence for bug fixes, and consistent repository terminology. Use when reviewing a diff or pull request. Do not use for implementing changes or posting GitHub review actions.","argument-hint":"Diff or pull request to review"},"isInternal":false,"tokens":320,"sizeBytes":1777},{"name":"EXAMPLE-README.md","path":"extensions/template/EXAMPLE-README.md","rawUrl":"https://raw.githubusercontent.com/github/spec-kit/HEAD/extensions/template/EXAMPLE-README.md","title":"Template Skill","category":"anthropic-skill","format":"markdown","content":"# EXAMPLE: Extension README\n\nThis is an example of what your extension README should look like after customization.\n**Delete this file and replace README.md with content similar to this.**\n\n---\n\n# My Extension\n\n\n\nBrief description of what your extension does and why it's useful.\n\n## Features\n\n\n\n- Feature 1: Description\n- Feature 2: Description\n- Feature 3: Description\n\n## Installation\n\n```bash\n# Install from catalog\nspecify extension add my-extension\n\n# Or install from local development directory\nspecify extension add --dev /path/to/my-extension\n```\n\n## Configuration\n\n1. Create configuration file:\n\n ```bash\n cp .specify/extensions/my-extension/config-template.yml \\\n .specify/extensions/my-extension/my-extension-config.yml\n ```\n\n2. Edit configuration:\n\n ```bash\n vim .specify/extensions/my-extension/my-extension-config.yml\n ```\n\n3. Set required values:\n \n ```yaml\n connection:\n url: \"https://api.example.com\"\n api_key: \"your-api-key\"\n\n project:\n id: \"your-project-id\"\n ```\n\n## Usage\n\n\n\n### Command: example\n\nDescription of what this command does.\n\n```bash\n# In Claude Code\n> /speckit.my-extension.example\n```\n\n**Prerequisites**:\n\n- Prerequisite 1\n- Prerequisite 2\n\n**Output**:\n\n- What this command produces\n- Where results are saved\n\n## Configuration Reference\n\n\n\n### Connection Settings\n\n| Setting | Type | Required | Description |\n|---------|------|----------|-------------|\n| `connection.url` | string | Yes | API endpoint URL |\n| `connection.api_key` | string | Yes | API authentication key |\n\n### Project Settings\n\n| Setting | Type | Required | Description |\n|---------|------|----------|-------------|\n| `project.id` | string | Yes | Project identifier |\n| `project.workspace` | string | No | Workspace or organization |\n\n## Environment Variables\n\nOverride configuration with environment variables:\n\n```bash\n# Override connection settings\nexport SPECKIT_MY_EXTENSION_CONNECTION_URL=\"https://custom-api.com\"\nexport SPECKIT_MY_EXTENSION_CONNECTION_API_KEY=\"custom-key\"\n```\n\n## Examples\n\n\n\n### Example 1: Basic Workflow\n\n```bash\n# Step 1: Create specification\n> /speckit.spec\n\n# Step 2: Generate tasks\n> /speckit.tasks\n\n# Step 3: Use extension\n> /speckit.my-extension.example\n```\n\n## Troubleshooting\n\n\n\n### Issue: Configuration not found\n\n**Solution**: Create config from template (see Configuration section)\n\n### Issue: Command not available\n\n**Solutions**:\n\n1. Check extension is installed: `specify extension list`\n2. Restart AI agent\n3. Reinstall extension\n\n## License\n\nMIT License - see LICENSE file\n\n## Support\n\n- **Issues**: \n- **Spec Kit Docs**: \n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history.\n\n---\n\n*Extension Version: 1.0.0*\n*Spec Kit: >=0.1.0*\n","isInternal":false,"tokens":721,"sizeBytes":3144},{"name":"README.md","path":"extensions/agent-context/README.md","rawUrl":"https://raw.githubusercontent.com/github/spec-kit/HEAD/extensions/agent-context/README.md","title":"agent-context Documentation","category":"plugin-manifest","format":"markdown","content":"# Coding Agent Context Extension\n\nThis bundled extension manages the **coding agent context/instruction file** (e.g. `CLAUDE.md`, `.github/copilot-instructions.md`, `AGENTS.md`, `GEMINI.md`, …) for the active integration.\n\nIt owns the lifecycle of the managed section delimited by the configurable start/end markers (defaults: `` / ``). For `.mdc` files, it also ensures the YAML frontmatter (the metadata block at the top of the file) contains `alwaysApply: true`. Otherwise, everything outside the managed section is untouched.\n\n> NOTE: Spec Kit itself never touches your agent context file. This extension is the only thing that does, and it's opt-in: install it if you want the block kept in sync, skip it if you'd rather manage that file yourself.\n\n## Why an extension?\n\nNot every Spec Kit user wants Spec Kit to write into the coding agent's context file. Keeping this behavior in a dedicated, **opt-in** extension lets users:\n\n- **Choose whether to install it at all** - `specify init` does **not** install it. Add it explicitly when you want Spec Kit to manage the agent context file; when it is absent, the file is never modified, and when it is disabled, its automatic hooks do not run.\n- **Customize the markers** by editing `.specify/extensions/agent-context/agent-context-config.yml` ([agent-context-config.yml](./agent-context-config.yml) in this repo) - the bundled scripts honor the `context_markers` value.\n- **Synchronize multiple agent anchors** by setting `context_files` when a project intentionally uses more than one coding agent context file, such as `AGENTS.md` and `CLAUDE.md`.\n- **Refresh on demand** by running the `speckit.agent-context.update` command in your agent, or automatically through the hooks declared in [extension.yml](./extension.yml) (`after_specify`, `after_plan`).\n\n## Installation\n\nTo install the extension, from the root of an initialized Spec Kit project, run:\n\n```bash\nspecify extension add agent-context\n```\n\n## Disabling\n\n```bash\nspecify extension disable agent-context\n\n# Re-enable it\nspecify extension enable agent-context\n```\n\nWhile this extension is disabled (or not installed), nothing in Spec Kit creates, updates, or removes the managed block - the `__CONTEXT_FILE__` placeholder in any template is left as-is, and the extension's own config is never read.\n\n## Commands\n\n| Command | Description |\n| ------------------------------ | --------------------------------------------------------------------------------- |\n| `speckit.agent-context.update` | Refresh the managed section in the agent context file with the current plan path. |\n\n> NOTE: The command ID above is canonical. Invoke it using the syntax for your integration: `/speckit.agent-context.update` for dot-command integrations; `/speckit-agent-context-update` for hyphen/skills integrations (including Forge and Cline); `$speckit-agent-context-update` for Codex or ZCode in skills mode; or `/skill:speckit-agent-context-update` for Kimi.\n\n## Configuration\n\nAll configuration flows through the extension's own config file at `.specify/extensions/agent-context/agent-context-config.yml` ([agent-context-config.yml](./agent-context-config.yml) in the repo).\n\n## Requirements\n\nThe bundled update scripts require **Python 3** with **PyYAML** for YAML/upsert processing (PowerShell can also use `ConvertFrom-Yaml` when available).\n\nPyYAML ships with the `specify` CLI and is normally available via the same `python3` interpreter. If a hook reports _\"PyYAML is required … not available in the current Python environment\"_, it means the system `python3` differs from the one used to install Spec Kit. To resolve, run:\n\n```bash\npip install pyyaml\n# or target the specific interpreter Spec Kit uses:\n/path/to/speckit-python -m pip install pyyaml\n```\n\n## Issues\n\nFor any other issues, please create an issue in the [official GitHub repo](https://github.com/github/spec-kit/issues).\n","isInternal":false,"tokens":873,"sizeBytes":4030},{"name":"README.md","path":"extensions/assess/README.md","rawUrl":"https://raw.githubusercontent.com/github/spec-kit/HEAD/extensions/assess/README.md","title":"assess Documentation","category":"plugin-manifest","format":"markdown","content":"# Idea Assessment Pipeline Extension\n\nA five-stage assessment pipeline for Spec Kit that turns **any idea** into a defensible **go / needs-clarification / kill** decision *before* it enters Spec-Driven Development. It is the missing **discovery track** that sits in front of the SDD **delivery track** (`specify → clarify → plan → tasks → analyze → implement`).\n\nDiscovery answers *\"is this worth building?\"* Delivery answers *\"how do we build it?\"* Only ideas that survive assessment hand off to `/speckit.specify`.\n\n## Overview\n\n`assess` runs inside an initialized Spec Kit project (it writes assessments under `.specify/assessments/`), but that project can be **completely empty of source code** — a freshly initialized project with no code works just as well as an established codebase. The input is just an idea: pasted text, a URL, or a ticket need no existing code, while a codebase pointer lets you assess an idea for code that already exists. Neither starting point is more \"correct\" than the other.\n\nEach idea lives in its own directory under `.specify/assessments//`, with one Markdown artifact per stage:\n\n```\n.specify/assessments//\n├── intake.md # speckit.assess.intake — capture the raw idea\n├── research.md # speckit.assess.research — gather (and challenge with) evidence\n├── problem.md # speckit.assess.define — define the problem, goals, metrics\n├── concept.md # speckit.assess.shape — shape solution options + appetite\n└── decision.md # speckit.assess.decide — go / needs-clarification / kill → handoff\n```\n\nThe pipeline is a **funnel**: most ideas should be killed or parked before `shape`. Killing an idea with a documented reason is a successful outcome, not a failure.\n\n```mermaid\nflowchart LR\n A[intake] --> R[research] --> D[define] --> S[shape] --> C{decide}\n C -->|go| SPEC[/speckit.specify/]\n C -->|kill| X[closed, recorded]\n C -.->|needs-clarification| F[refine named artifact in place]\n F -.->|then revise decision.md| C\n```\n\n## Commands\n\n| Command | Stage | Output |\n|---------|-------|--------|\n| `speckit.assess.intake` | Capture & normalize a raw idea (text, URL, ticket, or codebase pointer). | `intake.md` |\n| `speckit.assess.research` | Gather users/market/prior-art/data evidence — and evidence *against* the idea. | `research.md` |\n| `speckit.assess.define` | Define the problem: users, goals, non-goals, success metrics, cost of inaction. | `problem.md` |\n| `speckit.assess.shape` | Shape 2–3 concept-level options with appetite and trade-offs; recommend one (or none). | `concept.md` |\n| `speckit.assess.decide` | Score against criteria and render the verdict; hand `go` ideas to `/speckit.specify`. | `decision.md` |\n\nStages are meant to run in order but are not rigidly gated:\n\n- `define` is the minimum viable stage and can run directly on user input (intake/research optional).\n- `shape` requires `problem.md`.\n- `decide` requires `problem.md`; a `go` verdict expects `concept.md` (otherwise it is downgraded to `needs-clarification`).\n\n## Resolving clarifications\n\nThe normal process is sequential and each command usually runs **once**:\n\n```text\nintake → research → define → shape → decide\n```\n\nEach stage writes a Markdown artifact under `.specify/assessments//`. Those files stay editable. The commands keep their existing output templates: they do not rewrite an earlier artifact or perform that refinement themselves. `[NEEDS CLARIFICATION: …]` markers are gaps in the artifact, not a signal to regenerate the whole stage from scratch.\n\nResolve them by refining the existing file:\n\n1. **Edit the Markdown directly** (fill in the missing metric, owner, constraint, and so on), or\n2. **Ask the agent in free-form chat** to incorporate the missing information into that artifact.\n\nThen ask whether the new information clears the blocker and to update any downstream wording that depended on it. That includes `decision.md`: you can supply the missing facts and ask the agent to revise the scorecard, rationale, verdict, or handoff. That is artifact refinement, not command iteration.\n\nWhen you add evidence, keep the source and confidence tags the research stage already uses (`ASSUMPTION` vs cited claims). Do not invent citations.\n\nRerunning an earlier `speckit.assess.*` command is the exception (for example after a wrong slug or a discarded draft), not the default path for answering clarification markers.\n\n## Slug Conventions\n\nA *slug* is the per-idea directory name under `.specify/assessments/`. It is the handle all five commands share.\n\n- **User-provided**: normalized to lowercase kebab-case (e.g. `offline-mode`, `cut-onboarding-friction`). Preserved verbatim after normalization — no timestamps or numbers appended.\n- **Asked for**: in interactive use, `speckit.assess.intake` asks for a slug when none is supplied, suggesting a kebab-case default derived from the idea.\n- **Automated**: when no human is available, the agent generates a unique slug and never overwrites an existing assessment directory (appending `-2`, `-3`, … or a short date as needed).\n- **Reuse from context**: later stages reuse the slug reported earlier in the same session, confirmed by the presence of the assessment directory.\n\n## Installation\n\n```bash\nspecify extension add assess\n```\n\n## Disabling\n\n```bash\nspecify extension disable assess\nspecify extension enable assess\n```\n\n## Typical Flow\n\n```bash\n# 1. Capture an idea (pasted text, a URL, or \"assess this repo\")\n/speckit.assess.intake \"Let users work offline and sync when they reconnect\" slug=offline-mode\n\n# 2. Gather evidence — and reasons it might not be worth it\n/speckit.assess.research slug=offline-mode\n\n# 3. Define the actual problem\n/speckit.assess.define slug=offline-mode\n\n# 4. Shape 2–3 concept options with appetites\n/speckit.assess.shape slug=offline-mode\n\n# 5. Decide — go, clarify, or kill\n/speckit.assess.decide slug=offline-mode\n# → on \"go\", hand the decision.md handoff summary to /speckit.specify\n```\n\n## Handoff\n\n`assess` is a **standalone pipeline you enter deliberately** — it registers no lifecycle hooks and never inserts itself into `/speckit.specify`. The only coupling runs forward and by choice: a `go` verdict from `/speckit.assess.decide` hands its `decision.md` summary to `/speckit.specify`. Discovery and specification stay separate processes.\n\n## Guardrails\n\n- Only `speckit.assess.*` commands write, and only inside `.specify/assessments//`. **None of them modify source code** — solution design and implementation belong to the SDD lifecycle (`/speckit.specify` onward).\n- Web content fetched during `intake`/`research` is treated as untrusted data, governed by an explicit URL Trust Policy (allowlisted public sources fetched freely; unknown hosts prompted or skipped; loopback/RFC1918/metadata endpoints refused).\n- Evidence is never over-claimed: unsourced statements are tagged `ASSUMPTION`, and `research.md` always includes an *Evidence Against the Idea* section.\n- Verdicts are never over-claimed: a `go` requires a valid problem, `adequate`+ evidence (never weak/unknown), and a shaped concept; otherwise the honest verdict is `needs-clarification`.\n- Slugs are normalized to `[a-z0-9-]` and an empty result is rejected; before any read or write, each command also rejects symlinked path components and verifies the resolved path stays inside the project root — so an assessment can never escape `.specify/assessments/`, even in a crafted or cloned project.\n- No command overwrites an existing artifact without confirmation; in automated mode it refuses.\n\n## Relationship to Other Extensions\n\n`assess` is deliberately the **generic, role-neutral** discovery track — usable by a founder, PM, BA, engineer, or designer. Richer or more specialized pre-SDD flows in the community catalog (e.g. product-lifecycle orchestrators, technical-discovery, intake-normalization, brownfield onboarding) can layer on top of or feed into it; `assess` aims to be the minimal, opinionated funnel that ends cleanly at the `/speckit.specify` handoff.\n","isInternal":false,"tokens":1965,"sizeBytes":8127},{"name":"README.md","path":"extensions/bug/README.md","rawUrl":"https://raw.githubusercontent.com/github/spec-kit/HEAD/extensions/bug/README.md","title":"bug Documentation","category":"plugin-manifest","format":"markdown","content":"# Bug Triage Workflow Extension\n\nA three-step bug triage workflow for Spec Kit: assess, fix, and validate. Each bug lives in its own directory under `.specify/bugs//`, with one Markdown report per stage.\n\n## Overview\n\nThis extension delivers an opinionated, repeatable bug workflow that any AI coding agent can drive:\n\n1. **Assess** — read a bug report (pasted text or a URL), judge whether it is a real bug, locate suspected code paths, and propose a remediation.\n2. **Fix** — apply the proposed remediation and record exactly what changed.\n3. **Test** — re-run the reproduction and any added tests, then record the verification result.\n\nThe three stages communicate through three Markdown files in a single per-bug directory:\n\n```\n.specify/bugs//\n├── assessment.md # written by speckit.bug.assess\n├── fix.md # written by speckit.bug.fix\n└── test.md # written by speckit.bug.test\n```\n\n## Commands\n\n| Command | Description | Output |\n|---------|-------------|--------|\n| `speckit.bug.assess` | Triages a bug report (pasted text or URL) against the codebase. | `.specify/bugs//assessment.md` |\n| `speckit.bug.fix` | Applies the remediation from the assessment. | `.specify/bugs//fix.md` |\n| `speckit.bug.test` | Validates the fix and records the verification report. | `.specify/bugs//test.md` |\n\n## Slug Conventions\n\nA *slug* is the per-bug directory name under `.specify/bugs/`. It is the only handle the three commands share.\n\n- **User-provided**: any shape the user wants, normalized to lowercase kebab-case (e.g. `login-timeout`, `cve-2026-001`, `oauth-redirect-500`). The slug is preserved verbatim after normalization — no timestamps or numbers are appended automatically.\n- **Asked for**: in interactive use, `speckit.bug.assess` asks for a slug when none is supplied, suggesting a kebab-case default derived from the bug summary.\n- **Automated**: when no human is available to answer, the agent generates a slug itself. The generated slug **MUST** produce a unique directory — if `.specify/bugs//` already exists, the agent appends the shortest disambiguating suffix needed (`-2`, `-3`, …) or a short date (`-20260605`). Existing bug directories are never overwritten.\n\n## Installation\n\n```bash\n# Install the bundled bug extension (no network required)\nspecify extension add bug\n```\n\n## Disabling\n\n```bash\n# Disable the bug extension\nspecify extension disable bug\n\n# Re-enable it\nspecify extension enable bug\n```\n\n## Typical Flow\n\n```bash\n# 1. Triage a bug from a pasted stack trace\n/speckit.bug.assess \"TypeError: cannot read properties of undefined (reading 'token') at /auth/callback\"\n\n# 2. Triage a bug from a GitHub issue URL\n/speckit.bug.assess https://github.com/example/repo/issues/1234 slug=callback-token\n\n# 3. Apply the proposed fix\n/speckit.bug.fix slug=callback-token\n\n# 4. Validate the fix\n/speckit.bug.test slug=callback-token\n```\n\n## Guardrails\n\n- `speckit.bug.assess` and `speckit.bug.test` **never modify source code**. They read the repository and write only inside `.specify/bugs//`.\n- `speckit.bug.fix` is the only command that edits source code, and it stays within the files listed in the assessment unless new evidence requires expanding scope (which is logged in `fix.md` under **Deviations from Assessment**).\n- None of the commands overwrite an existing report file without explicit confirmation; in automated mode they refuse and pick a new unique slug instead.\n- Verdicts and verification results are never over-claimed: a reproduction that was not actually performed is reported as `partial` or `not-run`, not `verified`.\n\n## Hooks\n\nThis extension registers no hooks of its own. The three commands are always invoked explicitly by the user, but expose lifecycle events for other extensions:\n\n| Command | Before event | After event |\n|---------|--------------|-------------|\n| `speckit.bug.assess` | `before_bug_assess` | `after_bug_assess` |\n| `speckit.bug.fix` | `before_bug_fix` | `after_bug_fix` |\n| `speckit.bug.test` | `before_bug_test` | `after_bug_test` |\n\nPre-hooks run after slug resolution and prerequisites, before execution. For assessment, the bug directory already exists before the pre-hook runs. Post-hooks run after `assessment.md`, `fix.md`, or `test.md` is written and before reporting completion. An unintelligible pasted report keeps the existing early stop: no assessment report, post-hooks, or completion report. Before-hooks run before ingestion, so they can already have run when a report is rejected; the prerequisite bug directory is not removed. Hooks are prompts run in the same session; they reuse the resolved `BUG_SLUG` and `BUG_DIR` (and, for post-hooks, the written report) from the conversation, and no variables are injected.\n\nFor example, an installed intake extension can register a hook in `.specify/extensions.yml`:\n\n```yaml\nhooks:\n before_bug_assess:\n - extension: intake\n command: speckit.intake.collect\n enabled: true\n optional: false\n description: Collect evidence in the resolved bug directory\n```\n\nMandatory hooks are invoked and awaited; optional hooks are presented for the user to run. Disabled hooks and hooks with non-empty conditions are skipped by the command templates. With no registered hooks, the workflow proceeds as before. See the [Extension API Reference](../EXTENSION-API-REFERENCE.md#hook-events) for the shared hook contract.\n","isInternal":false,"tokens":1312,"sizeBytes":5443},{"name":"README.md","path":"extensions/git/README.md","rawUrl":"https://raw.githubusercontent.com/github/spec-kit/HEAD/extensions/git/README.md","title":"git Documentation","category":"plugin-manifest","format":"markdown","content":"# Git Branching Workflow Extension\n\nGit repository initialization, feature branch creation, numbering (sequential/timestamp), validation, remote detection, and auto-commit for Spec Kit.\n\n## Overview\n\nThis extension provides Git operations as an optional, self-contained module. It manages:\n\n- **Repository initialization** with configurable commit messages\n- **Feature branch creation** with sequential (`001-feature-name`) or timestamp (`20260319-143022-feature-name`) numbering and optional templates for branch namespaces\n- **Branch validation** to ensure branches follow naming conventions\n- **Git remote detection** for GitHub integration (e.g., issue creation)\n- **Auto-commit** after core commands (configurable per-command with custom messages, or Conventional Commit messages generated by the agent)\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `speckit.git.initialize` | Initialize a Git repository with a configurable commit message |\n| `speckit.git.feature` | Create a feature branch with sequential or timestamp numbering |\n| `speckit.git.validate` | Validate current branch follows feature branch naming conventions |\n| `speckit.git.remote` | Detect Git remote URL for GitHub integration |\n| `speckit.git.commit` | Auto-commit changes (configurable per-command enable/disable and messages) |\n\n## Hooks\n\n| Event | Command | Optional | Description |\n|-------|---------|----------|-------------|\n| `before_constitution` | `speckit.git.initialize` | No | Init git repo before constitution |\n| `before_specify` | `speckit.git.feature` | No | Create feature branch before specification |\n| `before_clarify` | `speckit.git.commit` | Yes | Commit outstanding changes before clarification |\n| `before_plan` | `speckit.git.commit` | Yes | Commit outstanding changes before planning |\n| `before_tasks` | `speckit.git.commit` | Yes | Commit outstanding changes before task generation |\n| `before_implement` | `speckit.git.commit` | Yes | Commit outstanding changes before implementation |\n| `before_checklist` | `speckit.git.commit` | Yes | Commit outstanding changes before checklist |\n| `before_analyze` | `speckit.git.commit` | Yes | Commit outstanding changes before analysis |\n| `before_taskstoissues` | `speckit.git.commit` | Yes | Commit outstanding changes before issue sync |\n| `after_constitution` | `speckit.git.commit` | Yes | Auto-commit after constitution update |\n| `after_specify` | `speckit.git.commit` | Yes | Auto-commit after specification |\n| `after_clarify` | `speckit.git.commit` | Yes | Auto-commit after clarification |\n| `after_plan` | `speckit.git.commit` | Yes | Auto-commit after planning |\n| `after_tasks` | `speckit.git.commit` | Yes | Auto-commit after task generation |\n| `after_implement` | `speckit.git.commit` | Yes | Auto-commit after implementation |\n| `after_checklist` | `speckit.git.commit` | Yes | Auto-commit after checklist |\n| `after_analyze` | `speckit.git.commit` | Yes | Auto-commit after analysis |\n| `after_taskstoissues` | `speckit.git.commit` | Yes | Auto-commit after issue sync |\n\n## Configuration\n\nConfiguration is stored in `.specify/extensions/git/git-config.yml`:\n\n```yaml\n# Branch numbering strategy: \"sequential\" or \"timestamp\"\nbranch_numbering: sequential\n\n# Optional branch name template. Leave empty for the default \"{number}-{slug}\".\n# Supported tokens: {author}, {app}, {number}, {slug}; {slug} must not appear\n# before {number}, and the final path segment must start with {number}-.\n# Example for monorepos: \"{author}/{app}/{number}-{slug}\"\nbranch_template: \"\"\n\n# Optional shorthand namespace. Leave empty to use branch_template/default behavior.\n# Example: \"features/{app}\" expands to \"features/{app}/{number}-{slug}\"\nbranch_prefix: \"\"\n\n# Custom commit message for git init\ninit_commit_message: \"[Spec Kit] Initial commit\"\n\n# Commit message style for auto-commit hooks: \"fixed\" (default) uses the\n# messages below; \"conventional\" asks the agent to generate a Conventional\n# Commit message (e.g. \"feat: add OAuth spec\") from the diff instead.\ncommit_style: fixed\n\n# Auto-commit per command (all disabled by default)\n# Example: enable auto-commit after specify\nauto_commit:\n default: false\n after_specify:\n enabled: true\n message: \"[Spec Kit] Add specification\"\n```\n\n`{author}` is derived from Git config and sanitized for branch names. `{app}` is derived from the Spec Kit init directory name. Custom templates must not put `{slug}` before `{number}`, and must put `{number}-` at the start of the final path segment so generated names remain valid feature branches. For a monorepo project at `apps/web/.specify/`, a template such as `{author}/{app}/{number}-{slug}` produces branches like `jdoe/web/008-guided-tour`.\n\nFor simple namespace-only customization, `branch_prefix` is also accepted as a shorthand and expands to `/{number}-{slug}`.\n\n## Installation\n\n```bash\n# Install the bundled git extension (no network required)\nspecify extension add git\n```\n\n## Disabling\n\n```bash\n# Disable the git extension (spec creation continues without branching)\nspecify extension disable git\n\n# Re-enable it\nspecify extension enable git\n```\n\n## Graceful Degradation\n\nWhen Git is not installed or the directory is not a Git repository:\n- Spec directories are still created under `specs/`\n- Branch creation is skipped with a warning\n- Branch validation is skipped with a warning\n- Remote detection returns empty results\n\n## Scripts\n\nThe extension bundles cross-platform scripts:\n\n- `scripts/bash/create-new-feature-branch.sh` — Bash implementation (branch creation only)\n- `scripts/bash/git-common.sh` — Shared Git utilities (Bash)\n- `scripts/powershell/create-new-feature-branch.ps1` — PowerShell implementation (branch creation only)\n- `scripts/powershell/git-common.ps1` — Shared Git utilities (PowerShell)\n","isInternal":false,"tokens":1311,"sizeBytes":5819},{"name":"README.md","path":"extensions/github/README.md","rawUrl":"https://raw.githubusercontent.com/github/spec-kit/HEAD/extensions/github/README.md","title":"github Documentation","category":"plugin-manifest","format":"markdown","content":"# GitHub Integration Extension\n\nThis bundled, **opt-in** extension is the home for Spec Kit's GitHub *platform* functionality. Today it provides one command, `speckit.github.taskstoissues`, which turns a feature's `tasks.md` into dependency-ordered GitHub issues.\n\n> NOTE: `git` and `github` are deliberately separate domains. The [`git` extension](../git/README.md) owns local version-control workflow (feature branches, commits, remote detection); this extension owns interactions with the GitHub platform itself.\n\n## Why an extension?\n\nCreating GitHub issues is provider-specific project management, not part of the provider-neutral Spec-Driven Development lifecycle. Keeping it in a dedicated, opt-in extension lets users:\n\n- **Choose whether to install it at all** — `specify init` does **not** install it.\n- **Use a different issue tracker** without having to work around a GitHub-specific core command.\n- **Depend on a stable, namespaced command** from other extensions.\n\n## Installation\n\nFrom the root of an initialized Spec Kit project:\n\n```bash\nspecify extension add github\n```\n\nThe `generic` (bring your own agent) integration registers this command under\nits configured `--commands-dir` in both commands and skills layouts. Installing\n`github` creates `speckit.github.taskstoissues.md` in commands mode or\n`speckit-github-taskstoissues/SKILL.md` in skills mode. The core\n`speckit.taskstoissues` command is deprecated but remains available during migration.\nUse this extension's recommended command instead. See\n[integration-specific options](../../docs/integrations/cli.md#integration-specific-options).\n\n## Removal\n\n```bash\nspecify extension remove github\n```\n\n## Commands\n\n| Command | Description |\n| ------------------------------ | -------------------------------------------------------------------- |\n| `speckit.github.taskstoissues` | Recommended: convert tasks from `tasks.md` into dependency-ordered GitHub issues. |\n\n> NOTE: The command ID above is canonical. Invoke it using the syntax for your integration: `/speckit.github.taskstoissues` for dot-command integrations; `/speckit-github-taskstoissues` for slash-hyphen integrations (including Forge and Cline); `$speckit-github-taskstoissues` for Codex, ZCode, or Command Code in skills mode; or `/skill:speckit-github-taskstoissues` for Kimi.\n\n### What the command does\n\n1. Resolves the active feature and loads its `tasks.md` (via this extension's own `resolve-tasks` script — see [Scripts](#scripts)).\n2. Reads the Git remote and **stops unless it points at GitHub**.\n3. Lists existing repository issues — open *and* closed — and matches their titles against the task IDs in `tasks.md` (`\\bT\\d{3,}\\b`, so four-digit and longer IDs are handled).\n4. Creates issues titled `T001: ` only for task IDs that do not already have one, in the repository identified by the remote.\n\n## Hooks\n\nThis extension consumes the existing `before_taskstoissues` and `after_taskstoissues` hook points, which are read from `.specify/extensions.yml` at run time. The hook keys are unchanged from the core command, so hooks registered by other extensions — for example the `git` extension's auto-commit hooks — keep firing exactly as before.\n\n## Requirements\n\n- Spec Kit **0.12.17 or newer**. Extension-local `scripts/...` path rewriting arrived in\n 0.12.6, but auto-registered skills did not resolve `__SPECKIT_COMMAND_*__` references\n until 0.12.17. Earlier releases cannot render this command correctly in every supported\n layout, so `specify extension add github` refuses to install below 0.12.17.\n- A Git remote pointing at GitHub.\n- The **GitHub MCP server** available to your coding agent, providing the `list_issues` and `issue_write` tools.\n\n> NOTE: Agents without MCP support (for example the Pi Coding Agent out of the box) cannot run this command as intended.\n\n## Scripts\n\nThe extension ships its own feature-resolution script in all three supported runtimes, so it is self-contained and does not reach into core:\n\n| Runtime | Script |\n| ---------- | ---------------------------------------- |\n| Bash | `scripts/bash/resolve-tasks.sh` |\n| PowerShell | `scripts/powershell/resolve-tasks.ps1` |\n| Python | `scripts/python/resolve_tasks.py` |\n\nOnce installed they live under `.specify/extensions/github/scripts/`. The script is a trimmed twin of core's `check-prerequisites`: it resolves the project root and active feature directory, requires `plan.md` and `tasks.md`, and reports the design docs alongside them. It matches the invocation the core command makes (`--require-tasks --include-tasks`), so `spec.md` stays optional. By default, a `SPECIFY_FEATURE_DIRECTORY` override is persisted to `.specify/feature.json` so a later run without the variable resolves to the same feature. When `SPECIFY_FEATURE_NO_PERSIST=1` or `true`, the override still selects the feature for this run, but the script does not create or modify `feature.json`.\n\nPrerequisite errors name the Spec Kit command without assuming an integration's invocation syntax. Use the syntax described under [Commands](#commands) for your integration.\n\n## Migrating from the core `taskstoissues` command\n\nSpec Kit is moving GitHub issue tracking out of core in three stages:\n\n1. **Initial stage (completed)** — this extension shipped with the core `/speckit.taskstoissues` command still available.\n2. **Next (current stage)** — the replacement has been available for at least one release, so the core command is now deprecated. It displays a migration warning and continues its existing workflow. It does not install or enable the extension automatically or run the replacement command.\n3. **Later** — the core command will be removed in a future minor release.\n\nFor existing projects, upgrading the CLI alone does not refresh the generated\ncore command files. After upgrading the CLI, run this from the project root:\n\n```bash\nspecify integration upgrade \n```\n\nReplace `` with the installed integration key, or omit it to upgrade the\ndefault integration. This refreshes the core command with the deprecation\nwarning. If locally modified files block the upgrade, inspect those changes\nbefore deciding whether to overwrite them. See [Upgrade an Integration](../../docs/integrations/cli.md#upgrade-an-integration).\n\nTo migrate, install the extension and use the namespaced command instead:\n\n```bash\nspecify extension add github\n```\n\nThe `generic` integration supports this migration in both commands and skills\nlayouts under its configured `--commands-dir`. The core command remains\navailable during this deprecation period until the removal stage.\n\n| Deprecated core command | Recommended extension command |\n| ------------------------- | --------------------------------- |\n| `/speckit.taskstoissues` | `/speckit.github.taskstoissues` |\n\nApart 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.\n\n### Presets and dependent extensions\n\nBefore the core command is removed, audit references to `speckit.taskstoissues`\nin presets, extension prompts, workflow steps, handoffs, and project automation.\nFor GitHub issue conversion, use the canonical `speckit.github.taskstoissues`\ncommand ID and render it with the agent-specific syntax under [Commands](#commands).\nReplace `__SPECKIT_COMMAND_TASKSTOISSUES__` cross-command references with\n`__SPECKIT_COMMAND_GITHUB_TASKSTOISSUES__` where template rendering is supported.\nDocument `specify extension add github` as a setup prerequisite; the deprecation\nwarning does not install this dependency.\n\nIf an extension proposal or external dependency declaration uses\n`requires.commands: [speckit.taskstoissues]`, update its target to\n`speckit.github.taskstoissues`. `requires.commands` is not an enforced dependency\nfield in the current extension manifest API, so do not rely on that declaration\nto install or check the GitHub extension. Follow the supported requirements in\nthe [extension API reference](../EXTENSION-API-REFERENCE.md#extension-manifest).\n\nPreset command overrides are separate from command references: an override of\n`speckit.taskstoissues` does not automatically customize the namespaced GitHub\ncommand. Review and port any needed customization, then verify the installed\ncommand in a sample project before retiring the old override. A preset that\nuses another issue tracker should retain its own provider-specific workflow\nrather than redirecting it to the GitHub command. Existing overrides may also\nhide the core deprecation warning, so communicate the migration to their users.\n\nKeep the `before_taskstoissues` and `after_taskstoissues` hook keys unchanged;\nboth commands consume them. Only update a hook's command reference if it invokes\nthe deprecated command. Do not invoke both core and replacement commands for\nthe same conversion, since that also runs their hooks twice. Publish and test\nupdated preset/extension versions before the later core-removal release.\n","isInternal":false,"tokens":1997,"sizeBytes":9457},{"name":"README.md","path":"extensions/README.md","rawUrl":"https://raw.githubusercontent.com/github/spec-kit/HEAD/extensions/README.md","title":"extensions Documentation","category":"plugin-manifest","format":"markdown","content":"# Spec Kit Extensions\n\nExtension system for [Spec Kit](https://github.com/github/spec-kit) - add new functionality without bloating the core framework.\n\n## Extension Catalogs\n\nSpec Kit provides two catalog files with different purposes:\n\n### Your Catalog (`catalog.json`)\n\n- **Purpose**: Default upstream catalog of extensions used by the Spec Kit CLI\n- **Default State**: Empty by design in the upstream project - you or your organization populate a fork/copy with extensions you trust\n- **Location (upstream)**: `extensions/catalog.json` in the GitHub-hosted spec-kit repo\n- **CLI Default**: The `specify extension` commands use the upstream catalog URL by default, unless overridden\n- **Org Catalog**: Point `SPECKIT_CATALOG_URL` at your organization's fork or hosted catalog JSON to use it instead of the upstream default\n- **Customization**: Copy entries from the community catalog into your org catalog, or add your own extensions directly\n\n**Example override:**\n```bash\n# Override the default upstream catalog with your organization's catalog\nexport SPECKIT_CATALOG_URL=\"https://your-org.com/spec-kit/catalog.json\"\nspecify extension search # Now uses your organization's catalog instead of the upstream default\n```\n\n### Community Reference Catalog (`catalog.community.json`)\n\n> [!NOTE]\n> Community extensions are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the extension code itself**. Review extension source code before installation and use at your own discretion.\n\n- **Purpose**: Browse available community-contributed extensions\n- **Status**: Active - contains extensions submitted by the community\n- **Location**: `extensions/catalog.community.json`\n- **Usage**: Reference catalog for discovering available extensions\n- **Submission**: Open to community contributions via [issue template](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml)\n\n**How It Works:**\n\n## Making Extensions Available\n\nYou control which extensions your team can discover and install:\n\n### Option 1: Curated Catalog (Recommended for Organizations)\n\nPopulate your `catalog.json` with approved extensions:\n\n1. **Discover** extensions from various sources:\n - Browse `catalog.community.json` for community extensions\n - Find private/internal extensions in your organization's repos\n - Discover extensions from trusted third parties\n2. **Review** extensions and choose which ones you want to make available\n3. **Add** those extension entries to your own `catalog.json`\n4. **Team members** can now discover and install them:\n - `specify extension search` shows your curated catalog\n - `specify extension add ` installs from your catalog\n\n**Benefits**: Full control over available extensions, team consistency, organizational approval workflow\n\n**Example**: Copy an entry from `catalog.community.json` to your `catalog.json`, then your team can discover and install it by name.\n\n### Option 2: Direct URLs (For Ad-hoc Use)\n\nSkip catalog curation - team members install directly using URLs:\n\n```bash\nspecify extension add --from https://github.com/org/spec-kit-ext/archive/refs/tags/v1.0.0.zip\n```\n\n**Benefits**: Quick for one-off testing or private extensions\n\n**Tradeoff**: Extensions installed this way won't appear in `specify extension search` for other team members unless you also add them to your `catalog.json`.\n\n## Available Community Extensions\n\n> [!NOTE]\n> Community extensions are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the extension code itself**. The Community Extensions website is also a third-party resource. Review extension source code before installation and use at your own discretion.\n\n🔍 **Browse and search community extensions on the [Community Extensions website](https://speckit-community.github.io/extensions/).**\n\nSee the [Community Extensions](https://github.github.io/spec-kit/community/extensions.html) page for the full list of available community-contributed extensions.\n\nFor the raw catalog data, see [`catalog.community.json`](catalog.community.json).\n\n\n## Adding Your Extension\n\n### Submission Process\n\nTo add your extension to the community catalog:\n\n1. **Prepare your extension** following the [Extension Development Guide](EXTENSION-DEVELOPMENT-GUIDE.md)\n2. **Create a GitHub release** for your extension\n3. **File an issue** using the [Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml) template with all required metadata\n4. **Wait for review** — a maintainer will review the submission, update the catalog, and close the issue\n\nSee the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) for detailed step-by-step instructions.\n\n### Submission Checklist\n\nBefore submitting, ensure:\n\n- ✅ Valid `extension.yml` manifest\n- ✅ Complete README with installation and usage instructions\n- ✅ LICENSE file included\n- ✅ GitHub release created with semantic version (e.g., v1.0.0)\n- ✅ Extension tested on a real project\n- ✅ All commands working as documented\n\n## Installing Extensions\nOnce extensions are available (either in your catalog or via direct URL), install them:\n\n```bash\n# From your curated catalog (by name)\nspecify extension search # See what's in your catalog\nspecify extension add # Install by name\n\n# Direct from URL (bypasses catalog)\nspecify extension add --from https://github.com///archive/refs/tags/.zip\n\n# List installed extensions\nspecify extension list\n```\n\nFor more information, see the [Extension User Guide](EXTENSION-USER-GUIDE.md).\n","isInternal":false,"tokens":1210,"sizeBytes":5902},{"name":"README.md","path":"extensions/template/README.md","rawUrl":"https://raw.githubusercontent.com/github/spec-kit/HEAD/extensions/template/README.md","title":"template Documentation","category":"plugin-manifest","format":"markdown","content":"# Extension Template\n\nStarter template for creating a Spec Kit extension.\n\n## Quick Start\n\n1. **Copy this template**:\n\n ```bash\n cp -r extensions/template my-extension\n cd my-extension\n ```\n\n2. **Customize `extension.yml`**:\n - Change extension ID, name, description\n - Update author and repository\n - Define your commands\n\n3. **Create commands**:\n - Add command files in `commands/` directory\n - Use Markdown format with YAML frontmatter\n\n4. **Create config template**:\n - Define configuration options\n - Document all settings\n\n5. **Write documentation**:\n - Update README.md with usage instructions\n - Add examples\n\n6. **Test locally**:\n\n ```bash\n cd /path/to/spec-kit-project\n specify extension add --dev /path/to/my-extension\n ```\n\n7. **Publish** (optional):\n - Create GitHub repository\n - Create release\n - Submit to catalog (see EXTENSION-PUBLISHING-GUIDE.md)\n\n## Files in This Template\n\n- `extension.yml` - Extension manifest (CUSTOMIZE THIS)\n- `config-template.yml` - Configuration template (CUSTOMIZE THIS)\n- `commands/example.md` - Example command (REPLACE THIS)\n- `README.md` - Extension documentation (REPLACE THIS)\n- `LICENSE` - MIT License (REVIEW THIS)\n- `CHANGELOG.md` - Version history (UPDATE THIS)\n- `.gitignore` - Git ignore rules\n\n## Customization Checklist\n\n- [ ] Update `extension.yml` with your extension details\n- [ ] Change extension ID to your extension name\n- [ ] Update author information\n- [ ] Define your commands\n- [ ] Create command files in `commands/`\n- [ ] Update config template\n- [ ] Write README with usage instructions\n- [ ] Add examples\n- [ ] Update LICENSE if needed\n- [ ] Test extension locally\n- [ ] Create git repository\n- [ ] Create first release\n\n## Need Help?\n\n- **Development Guide**: See EXTENSION-DEVELOPMENT-GUIDE.md\n- **API Reference**: See EXTENSION-API-REFERENCE.md\n- **Publishing Guide**: See EXTENSION-PUBLISHING-GUIDE.md\n- **User Guide**: See EXTENSION-USER-GUIDE.md\n\n## Template Version\n\n- Version: 1.0.0\n- Last Updated: 2026-01-28\n- Compatible with Spec Kit: >=0.1.0\n","isInternal":false,"tokens":527,"sizeBytes":2067}],"systemPromptSnippet":"\n\n# AGENTS.md\n\n## About Spec Kit and Specify\n\n**GitHub Spec Kit** is a comprehensive toolkit for implementing Spec-Driven Development (SDD) - a methodology that emphasizes creating clear specifications before implementation. The toolkit includes templates, scripts, and workflows that guide development teams through a structured approach to building software.\n\n**Specify CLI** is the command-line interface that bootstraps projects with the Spec Kit framework. It sets up the necessary directory structures, templates, and AI agent integrations to support the Spec-Driven Development workflow.\n\nThe toolkit supports multiple AI coding assistants, allowing teams to use their preferred tools while maintaining consistent project structure and development practices.\n\n## Adding or Updating CLI Commands\n\nBefore adding, updating, or reorganizing Specify CLI commands, read\n[Shared Command Application Architecture](design/shared.md) and\n[Specify CLI Command Architecture](design/cli.md). They define the shared\noperation boundary, command-module naming, private phases, nested command\ngroups, registration ownership, and mirrored tests.\n\n## Adding or Updating MCP Commands\n\nBefore adding or changing MCP tools for Specify commands, read\n[Shared Command Application Architecture](design/shared.md) and\n[Specify MCP Command Architecture](design/mcp.md). They define the shared\noperation boundary, typed contracts, explicit inventory, side-effect metadata,\nthe local stdio protocol boundary, and mirrored tests.\n\n## Adding or Updating Agent Integrations\n\nBefore adding or changing AI agent integrations, read\n[Agent Integration Design](design/integration.md). It covers\ndelivery routes, output formats, registration, and install/uninstall ownership.\n\n## Adding or Updating Workflow Steps\n\nBefore adding or changing workflow step types, read\n[Workflow Step Design](design/workflow-step.md). It covers registration,\nvalidation, execution, resume, and installed step packages.\n\n## Testing Executable Behavior\n\nBefore changing code or configuration that runs or controls execution without\nan LLM, read\n[Testing deterministic behavior](CONTRIBUTING.md#testing-deterministic-behavior).\nBehavioral changes need positive and negative coverage; bug fixes need\nbefore-and-after regression evidence.\n\n## PowerShell Compatibility\n\nAll PowerShell scripts in the repository and all generated PowerShell\nfunctionality MUST target Windows PowerShell 5.1, the version included with\nWindows. When adding or changing PowerShell code, use only syntax, cmdlets,\nparameters, and .NET APIs available in Windows PowerShell 5.1. Account for\nencoding and other runtime differences, preserve the required behavioral\nparity with Bash and Python implementations, and provide Windows PowerShell\n5.1 validation evidence for behavioral changes.\n\n## Branches and Agent Contributions\n\nWhen creating a branch, follow [Branch naming](CONTRIBUTING.md#branch-naming).\nBefore authoring commits, opening PRs, or posting review comments, read\n[Agent-authored Git and review activity](CONTRIBUTING.md#agent-authored-git-and-review-activity).\nAgent-authored commits and AI-generated PRs and comments each require their\nown disclosure; a PR-body disclosure alone does not cover later activity.\n\n## Other Contribution Guidance\n\nFor contribution or repository-workflow questions not covered above, or when\nthe applicable guidance is unclear, read [CONTRIBUTING.md](CONTRIBUTING.md)\nbefore acting.\n\n## Common Pitfalls\n\n- **Running tests against the wrong environment:** Run the suite inside this\n worktree's own virtualenv (`uv sync --extra test` then\n `.venv/bin/python -m pytest`). A bare `uv run pytest` can pick up an\n editable install from another worktree and fail to import new subpackages.\n\n\n---\nname: add-community-extension\ndescription: 'Add a community extension to the Spec Kit catalog from a GitHub issue submission. USE FOR: processing extension submission issues, validating catalog entries, updating catalog.community.json and docs/community/extensions.md, creating PRs. DO NOT USE FOR: creating new extensions from scratch, or first-party extension work.'\nargument-hint: 'GitHub issue URL or number for the extension submission'\n---\n\n# Add Community Extension\n\nProcess an extension submission issue and add or update it in the community catalog.\n\n## When to Use\n\n- A new `[Extension]` submission issue is filed\n- An existing extension submits an update issue (new version, changed metadata)\n- You need to add or update a community extension in `extensions/catalog.community.json` and `docs/community/extensions.md`\n\n## Procedure\n\n### 1. Fetch the submission issue\n\nRead the GitHub issue to extract all metadata:\n- Extension ID, name, version, description, author\n- Repository URL, download URL, homepage, documentation, changelog\n- License, required spec-kit version, optional tool dependencies\n- Number of commands and hooks\n- Tags\n\n### 2. Validate against publishing rules\n\nCheck **all** of the following (per `extensions/EXTENSION-PUBLISHING-GUIDE.md`):\n\n| Check | How |\n|-------|-----|\n| Repository exists and is public | Fetch the repository URL |\n| `extension.yml` manifest present | Confirm in repo file listing |\n| README.md present | Confirm in repo file listing |\n| LICENSE file present | Confirm in repo file listing |\n| GitHub release exists matching version | Check releases on the repo page |\n| Download URL is accessible | Verify it follows `archive/refs/tags/vX.Y.Z.zip` pattern and release exists |\n| Extension ID is lowercase-with-hyphens only | Regex: `^[a-z][a-z0-9-]*$` |\n| Version follows semver | Format: `X.Y.Z` |\n| Submission checklists are all checked | Confirm in issue body |\n\n### 3. Determine if this is an add or update\n\nSearch `extensions/catalog.community.json` for the extension ID.\n\n- **Not found** → this is a **new addition**. Proceed to step 4.\n- **Found** → this is an **update**. Proceed to step 4 but replace the existing entry in-place instead of inserting.\n\n### 4. Add or update `extensions/catalog.community.json`\n\n**New extension:** Insert the entry in **alphabetical order** by extension ID.\n\n**Update:** Replace the existing entry in-place. Update only the fields that changed (typically `version`, `download_url`, `description`, `provides`, `requires`, `tags`, `updated_at`). Preserve `created_at` and `downloads`/`stars` from the existing entry.\n\nUse the existing entries as the format template. Required fields:\n\n```json\n{\n \"\": {\n \"name\": \"\",\n \"id\": \"\",\n \"description\": \"\",\n \"author\": \"\",\n \"version\": \"\",\n \"download_url\": \"\",\n \"repository\": \"\",\n \"homepage\": \"\",\n \"documentation\": \"\",\n \"changelog\": \"\",\n \"license\": \"\",\n \"category\": \"\",\n \"effect\": \"\",\n \"requires\": {\n \"speckit_version\": \"\"\n },\n \"provides\": {\n \"commands\": ,\n \"hooks\": \n },\n \"tags\": [\"\", \"\"],\n \"verified\": false,\n \"downloads\": 0,\n \"stars\": 0,\n \"created_at\": \"T00:00:00Z\",\n \"updated_at\": \"T00:00:00Z\"\n }\n}\n```\n\n**Category** — free-form string; common values: `docs`, `code`, `process`, `integration`, `visibility`\n**Effect** — one of: `read-only`, `read-write`\n\nIf the extension has optional tool dependencies, add a `\"tools\"` array inside `\"requires\"`:\n\n```json\n\"tools\": [{ \"name\": \"\", \"required\": false }]\n```\n\nAlso update the top-level `\"updated_at\"` timestamp in the catalog.\n\nAfter editing, **validate the JSON** by running:\n\n```bash\npython3 -c \"import json; json.load(open('extensions/catalog.community.json')); print('Valid JSON')\"\n```\n\n### 5. Add or update `docs/community/extensions.md` community extensions table\n\n**New extension:** Insert a new row into the `# Community Extensions` table in **alphabetical order** by extension name.\n\n**Update:** Find the existing row and update the description or other changed fields in-place.\n\nDetermine the category and effect from the extension's behavior:\n\n```\n| | | `` | | []() |\n```\n\n**Category** — free-form; common values: `docs`, `code`, `process`, `integration`, `visibility`\n**Effect** — write canonical values `read-only` or `read-write` in `extension.yml` and `catalog.community.json`; use `Read-only`/`Read+Write` only for the docs table display\n\n### 6. Commit, push, and open PR\n\nUse `add-` for new extensions, `update-` for updates:\n\n```bash\n# New extension\ngit checkout -b add--extension\n\n# Update\ngit checkout -b update--extension\n```\n\n```bash\ngit add extensions/catalog.community.json docs/community/extensions.md\n\n# New extension\ngit commit -m \"Add extension to community catalog\n\nAdd extension submitted by @ to:\n- extensions/catalog.community.json (alphabetical order)\n- docs/community/extensions.md community extensions table\n\nCloses #\"\n\n# Update\ngit commit -m \"Update extension to v\n\nUpdate extension submitted by @:\n- extensions/catalog.community.json (version, download_url, etc.)\n- docs/community/extensions.md community extensions table\n\nCloses #\"\n\ngit push origin \n```\n\nThen create a PR to `upstream` (`github/spec-kit`) with:\n- **Title:** `Add extension to community catalog` (or `Update extension to v`)\n- **Body:** Include validation summary, `Closes #`, and `cc @`\n- **Head:** `:`\n- **Base:** `main`\n\n## Common Pitfalls\n\n- **Alphabetical order matters** — entries must be sorted by ID in the JSON and by name in the docs table.\n- **Don't forget the catalog `updated_at`** — the top-level timestamp in `catalog.community.json` must be refreshed.\n- **Validate JSON after editing** — a trailing comma or missing brace will break the catalog.\n- **Use `Closes` not `Fixes`** — `Closes #N` is the correct keyword for submission issues.\n- **Match the proposed entry but verify** — the issue may include a proposed JSON block, but always validate field values against the actual repository state.\n- **Preserve `created_at` on updates** — keep the original `created_at` value; only change `updated_at`.\n- **Preserve `downloads` and `stars` on updates** — these reflect usage metrics and must not be reset.\n\n\n---\nname: code-review\ndescription: Reviews Spec Kit code changes for consistency with applicable design documents, positive and negative test coverage, regression evidence for bug fixes, and consistent repository terminology. Use when reviewing a diff or pull request. Do not use for implementing changes or posting GitHub review actions.\nargument-hint: 'Diff or pull request to review'\n---\n\n# Code Review\n\n1. Ensure each code change has test cases that verify what the code should do and what it should prevent.\n2. Ensure bug-fix pull requests include a regression test that demonstrates the bug was reproducible before the change and is fixed afterward; if the reviewer cannot run the comparison, use available evidence and state that limitation.\n3. Ensure wording changes use repository-consistent terms; exclude community-authored catalog content and its generated documentation from this check.\n4. Identify the affected domains and read the applicable documents in `design/` before evaluating architectural consistency. For CLI command changes, use `design/cli.md`; for agent integrations, use `design/integration.md`; for workflow step types, use `design/workflow-step.md`. Read other design documents when relevant, not every document for every PR.\n5. Check the changes against the applicable design requirements, including implementation boundaries, ownership, lifecycle, and delivery requirements. Reference the documents rather than duplicating their rules in this skill. Cite the document and section for each reported mismatch.\n6. Distinguish an unexplained design violation from an intentional design change. Evaluate the rationale and evidence for an intentional change; updating the design document alone does not establish that the implementation is justified.\n\n\n# EXAMPLE: Extension README\n\nThis is an example of what your extension README should look like after customization.\n**Delete this file and replace README.md with content similar to this.**\n\n---\n\n# My Extension\n\n\n\nBrief description of what your extension does and why it's useful.\n\n## Features\n\n\n\n- Feature 1: Description\n- Feature 2: Description\n- Feature 3: Description\n\n## Installation\n\n```bash\n# Install from catalog\nspecify extension add my-extension\n\n# Or install from local development directory\nspecify extension add --dev /path/to/my-extension\n```\n\n## Configuration\n\n1. Create configuration file:\n\n ```bash\n cp .specify/extensions/my-extension/config-template.yml \\\n .specify/extensions/my-extension/my-extension-config.yml\n ```\n\n2. Edit configuration:\n\n ```bash\n vim .specify/extensions/my-extension/my-extension-config.yml\n ```\n\n3. Set required values:\n \n ```yaml\n connection:\n url: \"https://api.example.com\"\n api_key: \"your-api-key\"\n\n project:\n id: \"your-project-id\"\n ```\n\n## Usage\n\n\n\n### Command: example\n\nDescription of what this command does.\n\n```bash\n# In Claude Code\n> /speckit.my-extension.example\n```\n\n**Prerequisites**:\n\n- Prerequisite 1\n- Prerequisite 2\n\n**Output**:\n\n- What this command produces\n- Where results are saved\n\n## Configuration Reference\n\n\n\n### Connection Settings\n\n| Setting | Type | Required | Description |\n|---------|------|----------|-------------|\n| `connection.url` | string | Yes | API endpoint URL |\n| `connection.api_key` | string | Yes | API authentication key |\n\n### Project Settings\n\n| Setting | Type | Required | Description |\n|---------|------|----------|-------------|\n| `project.id` | string | Yes | Project identifier |\n| `project.workspace` | string | No | Workspace or organization |\n\n## Environment Variables\n\nOverride configuration with environment variables:\n\n```bash\n# Override connection settings\nexport SPECKIT_MY_EXTENSION_CONNECTION_URL=\"https://custom-api.com\"\nexport SPECKIT_MY_EXTENSION_CONNECTION_API_KEY=\"custom-key\"\n```\n\n## Examples\n\n\n\n### Example 1: Basic Workflow\n\n```bash\n# Step 1: Create specification\n> /speckit.spec\n\n# Step 2: Generate tasks\n> /speckit.tasks\n\n# Step 3: Use extension\n> /speckit.my-extension.example\n```\n\n## Troubleshooting\n\n\n\n### Issue: Configuration not found\n\n**Solution**: Create config from template (see Configuration section)\n\n### Issue: Command not available\n\n**Solutions**:\n\n1. Check extension is installed: `specify extension list`\n2. Restart AI agent\n3. Reinstall extension\n\n## License\n\nMIT License - see LICENSE file\n\n## Support\n\n- **Issues**: \n- **Spec Kit Docs**: \n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history.\n\n---\n\n*Extension Version: 1.0.0*\n*Spec Kit: >=0.1.0*\n\n\n# Coding Agent Context Extension\n\nThis bundled extension manages the **coding agent context/instruction file** (e.g. `CLAUDE.md`, `.github/copilot-instructions.md`, `AGENTS.md`, `GEMINI.md`, …) for the active integration.\n\nIt owns the lifecycle of the managed section delimited by the configurable start/end markers (defaults: `` / ``). For `.mdc` files, it also ensures the YAML frontmatter (the metadata block at the top of the file) contains `alwaysApply: true`. Otherwise, everything outside the managed section is untouched.\n\n> NOTE: Spec Kit itself never touches your agent context file. This extension is the only thing that does, and it's opt-in: install it if you want the block kept in sync, skip it if you'd rather manage that file yourself.\n\n## Why an extension?\n\nNot every Spec Kit user wants Spec Kit to write into the coding agent's context file. Keeping this behavior in a dedicated, **opt-in** extension lets users:\n\n- **Choose whether to install it at all** - `specify init` does **not** install it. Add it explicitly when you want Spec Kit to manage the agent context file; when it is absent, the file is never modified, and when it is disabled, its automatic hooks do not run.\n- **Customize the markers** by editing `.specify/extensions/agent-context/agent-context-config.yml` ([agent-context-config.yml](./agent-context-config.yml) in this repo) - the bundled scripts honor the `context_markers` value.\n- **Synchronize multiple agent anchors** by setting `context_files` when a project intentionally uses more than one coding agent context file, such as `AGENTS.md` and `CLAUDE.md`.\n- **Refresh on demand** by running the `speckit.agent-context.update` command in your agent, or automatically through the hooks declared in [extension.yml](./extension.yml) (`after_specify`, `after_plan`).\n\n## Installation\n\nTo install the extension, from the root of an initialized Spec Kit project, run:\n\n```bash\nspecify extension add agent-context\n```\n\n## Disabling\n\n```bash\nspecify extension disable agent-context\n\n# Re-enable it\nspecify extension enable agent-context\n```\n\nWhile this extension is disabled (or not installed), nothing in Spec Kit creates, updates, or removes the managed block - the `__CONTEXT_FILE__` placeholder in any template is left as-is, and the extension's own config is never read.\n\n## Commands\n\n| Command | Description |\n| ------------------------------ | --------------------------------------------------------------------------------- |\n| `speckit.agent-context.update` | Refresh the managed section in the agent context file with the current plan path. |\n\n> NOTE: The command ID above is canonical. Invoke it using the syntax for your integration: `/speckit.agent-context.update` for dot-command integrations; `/speckit-agent-context-update` for hyphen/skills integrations (including Forge and Cline); `$speckit-agent-context-update` for Codex or ZCode in skills mode; or `/skill:speckit-agent-context-update` for Kimi.\n\n## Configuration\n\nAll configuration flows through the extension's own config file at `.specify/extensions/agent-context/agent-context-config.yml` ([agent-context-config.yml](./agent-context-config.yml) in the repo).\n\n## Requirements\n\nThe bundled update scripts require **Python 3** with **PyYAML** for YAML/upsert processing (PowerShell can also use `ConvertFrom-Yaml` when available).\n\nPyYAML ships with the `specify` CLI and is normally available via the same `python3` interpreter. If a hook reports _\"PyYAML is required … not available in the current Python environment\"_, it means the system `python3` differs from the one used to install Spec Kit. To resolve, run:\n\n```bash\npip install pyyaml\n# or target the specific interpreter Spec Kit uses:\n/path/to/speckit-python -m pip install pyyaml\n```\n\n## Issues\n\nFor any other issues, please create an issue in the [official GitHub repo](https://github.com/github/spec-kit/issues).\n\n\n# Idea Assessment Pipeline Extension\n\nA five-stage assessment pipeline for Spec Kit that turns **any idea** into a defensible **go / needs-clarification / kill** decision *before* it enters Spec-Driven Development. It is the missing **discovery track** that sits in front of the SDD **delivery track** (`specify → clarify → plan → tasks → analyze → implement`).\n\nDiscovery answers *\"is this worth building?\"* Delivery answers *\"how do we build it?\"* Only ideas that survive assessment hand off to `/speckit.specify`.\n\n## Overview\n\n`assess` runs inside an initialized Spec Kit project (it writes assessments under `.specify/assessments/`), but that project can be **completely empty of source code** — a freshly initialized project with no code works just as well as an established codebase. The input is just an idea: pasted text, a URL, or a ticket need no existing code, while a codebase pointer lets you assess an idea for code that already exists. Neither starting point is more \"correct\" than the other.\n\nEach idea lives in its own directory under `.specify/assessments//`, with one Markdown artifact per stage:\n\n```\n.specify/assessments//\n├── intake.md # speckit.assess.intake — capture the raw idea\n├── research.md # speckit.assess.research — gather (and challenge with) evidence\n├── problem.md # speckit.assess.define — define the problem, goals, metrics\n├── concept.md # speckit.assess.shape — shape solution options + appetite\n└── decision.md # speckit.assess.decide — go / needs-clarification / kill → handoff\n```\n\nThe pipeline is a **funnel**: most ideas should be killed or parked before `shape`. Killing an idea with a documented reason is a successful outcome, not a failure.\n\n```mermaid\nflowchart LR\n A[intake] --> R[research] --> D[define] --> S[shape] --> C{decide}\n C -->|go| SPEC[/speckit.specify/]\n C -->|kill| X[closed, recorded]\n C -.->|needs-clarification| F[refine named artifact in place]\n F -.->|then revise decision.md| C\n```\n\n## Commands\n\n| Command | Stage | Output |\n|---------|-------|--------|\n| `speckit.assess.intake` | Capture & normalize a raw idea (text, URL, ticket, or codebase pointer). | `intake.md` |\n| `speckit.assess.research` | Gather users/market/prior-art/data evidence — and evidence *against* the idea. | `research.md` |\n| `speckit.assess.define` | Define the problem: users, goals, non-goals, success metrics, cost of inaction. | `problem.md` |\n| `speckit.assess.shape` | Shape 2–3 concept-level options with appetite and trade-offs; recommend one (or none). | `concept.md` |\n| `speckit.assess.decide` | Score against criteria and render the verdict; hand `go` ideas to `/speckit.specify`. | `decision.md` |\n\nStages are meant to run in order but are not rigidly gated:\n\n- `define` is the minimum viable stage and can run directly on user input (intake/research optional).\n- `shape` requires `problem.md`.\n- `decide` requires `problem.md`; a `go` verdict expects `concept.md` (otherwise it is downgraded to `needs-clarification`).\n\n## Resolving clarifications\n\nThe normal process is sequential and each command usually runs **once**:\n\n```text\nintake → research → define → shape → decide\n```\n\nEach stage writes a Markdown artifact under `.specify/assessments//`. Those files stay editable. The commands keep their existing output templates: they do not rewrite an earlier artifact or perform that refinement themselves. `[NEEDS CLARIFICATION: …]` markers are gaps in the artifact, not a signal to regenerate the whole stage from scratch.\n\nResolve them by refining the existing file:\n\n1. **Edit the Markdown directly** (fill in the missing metric, owner, constraint, and so on), or\n2. **Ask the agent in free-form chat** to incorporate the missing information into that artifact.\n\nThen ask whether the new information clears the blocker and to update any downstream wording that depended on it. That includes `decision.md`: you can supply the missing facts and ask the agent to revise the scorecard, rationale, verdict, or handoff. That is artifact refinement, not command iteration.\n\nWhen you add evidence, keep the source and confidence tags the research stage already uses (`ASSUMPTION` vs cited claims). Do not invent citations.\n\nRerunning an earlier `speckit.assess.*` command is the exception (for example after a wrong slug or a discarded draft), not the default path for answering clarification markers.\n\n## Slug Conventions\n\nA *slug* is the per-idea directory name under `.specify/assessments/`. It is the handle all five commands share.\n\n- **User-provided**: normalized to lowercase kebab-case (e.g. `offline-mode`, `cut-onboarding-friction`). Preserved verbatim after normalization — no timestamps or numbers appended.\n- **Asked for**: in interactive use, `speckit.assess.intake` asks for a slug when none is supplied, suggesting a kebab-case default derived from the idea.\n- **Automated**: when no human is available, the agent generates a unique slug and never overwrites an existing assessment directory (appending `-2`, `-3`, … or a short date as needed).\n- **Reuse from context**: later stages reuse the slug reported earlier in the same session, confirmed by the presence of the assessment directory.\n\n## Installation\n\n```bash\nspecify extension add assess\n```\n\n## Disabling\n\n```bash\nspecify extension disable assess\nspecify extension enable assess\n```\n\n## Typical Flow\n\n```bash\n# 1. Capture an idea (pasted text, a URL, or \"assess this repo\")\n/speckit.assess.intake \"Let users work offline and sync when they reconnect\" slug=offline-mode\n\n# 2. Gather evidence — and reasons it might not be worth it\n/speckit.assess.research slug=offline-mode\n\n# 3. Define the actual problem\n/speckit.assess.define slug=offline-mode\n\n# 4. Shape 2–3 concept options with appetites\n/speckit.assess.shape slug=offline-mode\n\n# 5. Decide — go, clarify, or kill\n/speckit.assess.decide slug=offline-mode\n# → on \"go\", hand the decision.md handoff summary to /speckit.specify\n```\n\n## Handoff\n\n`assess` is a **standalone pipeline you enter deliberately** — it registers no lifecycle hooks and never inserts itself into `/speckit.specify`. The only coupling runs forward and by choice: a `go` verdict from `/speckit.assess.decide` hands its `decision.md` summary to `/speckit.specify`. Discovery and specification stay separate processes.\n\n## Guardrails\n\n- Only `speckit.assess.*` commands write, and only inside `.specify/assessments//`. **None of them modify source code** — solution design and implementation belong to the SDD lifecycle (`/speckit.specify` onward).\n- Web content fetched during `intake`/`research` is treated as untrusted data, governed by an explicit URL Trust Policy (allowlisted public sources fetched freely; unknown hosts prompted or skipped; loopback/RFC1918/metadata endpoints refused).\n- Evidence is never over-claimed: unsourced statements are tagged `ASSUMPTION`, and `research.md` always includes an *Evidence Against the Idea* section.\n- Verdicts are never over-claimed: a `go` requires a valid problem, `adequate`+ evidence (never weak/unknown), and a shaped concept; otherwise the honest verdict is `needs-clarification`.\n- Slugs are normalized to `[a-z0-9-]` and an empty result is rejected; before any read or write, each command also rejects symlinked path components and verifies the resolved path stays inside the project root — so an assessment can never escape `.specify/assessments/`, even in a crafted or cloned project.\n- No command overwrites an existing artifact without confirmation; in automated mode it refuses.\n\n## Relationship to Other Extensions\n\n`assess` is deliberately the **generic, role-neutral** discovery track — usable by a founder, PM, BA, engineer, or designer. Richer or more specialized pre-SDD flows in the community catalog (e.g. product-lifecycle orchestrators, technical-discovery, intake-normalization, brownfield onboarding) can layer on top of or feed into it; `assess` aims to be the minimal, opinionated funnel that ends cleanly at the `/speckit.specify` handoff.\n\n\n# Bug Triage Workflow Extension\n\nA three-step bug triage workflow for Spec Kit: assess, fix, and validate. Each bug lives in its own directory under `.specify/bugs//`, with one Markdown report per stage.\n\n## Overview\n\nThis extension delivers an opinionated, repeatable bug workflow that any AI coding agent can drive:\n\n1. **Assess** — read a bug report (pasted text or a URL), judge whether it is a real bug, locate suspected code paths, and propose a remediation.\n2. **Fix** — apply the proposed remediation and record exactly what changed.\n3. **Test** — re-run the reproduction and any added tests, then record the verification result.\n\nThe three stages communicate through three Markdown files in a single per-bug directory:\n\n```\n.specify/bugs//\n├── assessment.md # written by speckit.bug.assess\n├── fix.md # written by speckit.bug.fix\n└── test.md # written by speckit.bug.test\n```\n\n## Commands\n\n| Command | Description | Output |\n|---------|-------------|--------|\n| `speckit.bug.assess` | Triages a bug report (pasted text or URL) against the codebase. | `.specify/bugs//assessment.md` |\n| `speckit.bug.fix` | Applies the remediation from the assessment. | `.specify/bugs//fix.md` |\n| `speckit.bug.test` | Validates the fix and records the verification report. | `.specify/bugs//test.md` |\n\n## Slug Conventions\n\nA *slug* is the per-bug directory name under `.specify/bugs/`. It is the only handle the three commands share.\n\n- **User-provided**: any shape the user wants, normalized to lowercase kebab-case (e.g. `login-timeout`, `cve-2026-001`, `oauth-redirect-500`). The slug is preserved verbatim after normalization — no timestamps or numbers are appended automatically.\n- **Asked for**: in interactive use, `speckit.bug.assess` asks for a slug when none is supplied, suggesting a kebab-case default derived from the bug summary.\n- **Automated**: when no human is available to answer, the agent generates a slug itself. The generated slug **MUST** produce a unique directory — if `.specify/bugs//` already exists, the agent appends the shortest disambiguating suffix needed (`-2`, `-3`, …) or a short date (`-20260605`). Existing bug directories are never overwritten.\n\n## Installation\n\n```bash\n# Install the bundled bug extension (no network required)\nspecify extension add bug\n```\n\n## Disabling\n\n```bash\n# Disable the bug extension\nspecify extension disable bug\n\n# Re-enable it\nspecify extension enable bug\n```\n\n## Typical Flow\n\n```bash\n# 1. Triage a bug from a pasted stack trace\n/speckit.bug.assess \"TypeError: cannot read properties of undefined (reading 'token') at /auth/callback\"\n\n# 2. Triage a bug from a GitHub issue URL\n/speckit.bug.assess https://github.com/example/repo/issues/1234 slug=callback-token\n\n# 3. Apply the proposed fix\n/speckit.bug.fix slug=callback-token\n\n# 4. Validate the fix\n/speckit.bug.test slug=callback-token\n```\n\n## Guardrails\n\n- `speckit.bug.assess` and `speckit.bug.test` **never modify source code**. They read the repository and write only inside `.specify/bugs//`.\n- `speckit.bug.fix` is the only command that edits source code, and it stays within the files listed in the assessment unless new evidence requires expanding scope (which is logged in `fix.md` under **Deviations from Assessment**).\n- None of the commands overwrite an existing report file without explicit confirmation; in automated mode they refuse and pick a new unique slug instead.\n- Verdicts and verification results are never over-claimed: a reproduction that was not actually performed is reported as `partial` or `not-run`, not `verified`.\n\n## Hooks\n\nThis extension registers no hooks of its own. The three commands are always invoked explicitly by the user, but expose lifecycle events for other extensions:\n\n| Command | Before event | After event |\n|---------|--------------|-------------|\n| `speckit.bug.assess` | `before_bug_assess` | `after_bug_assess` |\n| `speckit.bug.fix` | `before_bug_fix` | `after_bug_fix` |\n| `speckit.bug.test` | `before_bug_test` | `after_bug_test` |\n\nPre-hooks run after slug resolution and prerequisites, before execution. For assessment, the bug directory already exists before the pre-hook runs. Post-hooks run after `assessment.md`, `fix.md`, or `test.md` is written and before reporting completion. An unintelligible pasted report keeps the existing early stop: no assessment report, post-hooks, or completion report. Before-hooks run before ingestion, so they can already have run when a report is rejected; the prerequisite bug directory is not removed. Hooks are prompts run in the same session; they reuse the resolved `BUG_SLUG` and `BUG_DIR` (and, for post-hooks, the written report) from the conversation, and no variables are injected.\n\nFor example, an installed intake extension can register a hook in `.specify/extensions.yml`:\n\n```yaml\nhooks:\n before_bug_assess:\n - extension: intake\n command: speckit.intake.collect\n enabled: true\n optional: false\n description: Collect evidence in the resolved bug directory\n```\n\nMandatory hooks are invoked and awaited; optional hooks are presented for the user to run. Disabled hooks and hooks with non-empty conditions are skipped by the command templates. With no registered hooks, the workflow proceeds as before. See the [Extension API Reference](../EXTENSION-API-REFERENCE.md#hook-events) for the shared hook contract.\n\n\n# Git Branching Workflow Extension\n\nGit repository initialization, feature branch creation, numbering (sequential/timestamp), validation, remote detection, and auto-commit for Spec Kit.\n\n## Overview\n\nThis extension provides Git operations as an optional, self-contained module. It manages:\n\n- **Repository initialization** with configurable commit messages\n- **Feature branch creation** with sequential (`001-feature-name`) or timestamp (`20260319-143022-feature-name`) numbering and optional templates for branch namespaces\n- **Branch validation** to ensure branches follow naming conventions\n- **Git remote detection** for GitHub integration (e.g., issue creation)\n- **Auto-commit** after core commands (configurable per-command with custom messages, or Conventional Commit messages generated by the agent)\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `speckit.git.initialize` | Initialize a Git repository with a configurable commit message |\n| `speckit.git.feature` | Create a feature branch with sequential or timestamp numbering |\n| `speckit.git.validate` | Validate current branch follows feature branch naming conventions |\n| `speckit.git.remote` | Detect Git remote URL for GitHub integration |\n| `speckit.git.commit` | Auto-commit changes (configurable per-command enable/disable and messages) |\n\n## Hooks\n\n| Event | Command | Optional | Description |\n|-------|---------|----------|-------------|\n| `before_constitution` | `speckit.git.initialize` | No | Init git repo before constitution |\n| `before_specify` | `speckit.git.feature` | No | Create feature branch before specification |\n| `before_clarify` | `speckit.git.commit` | Yes | Commit outstanding changes before clarification |\n| `before_plan` | `speckit.git.commit` | Yes | Commit outstanding changes before planning |\n| `before_tasks` | `speckit.git.commit` | Yes | Commit outstanding changes before task generation |\n| `before_implement` | `speckit.git.commit` | Yes | Commit outstanding changes before implementation |\n| `before_checklist` | `speckit.git.commit` | Yes | Commit outstanding changes before checklist |\n| `before_analyze` | `speckit.git.commit` | Yes | Commit outstanding changes before analysis |\n| `before_taskstoissues` | `speckit.git.commit` | Yes | Commit outstanding changes before issue sync |\n| `after_constitution` | `speckit.git.commit` | Yes | Auto-commit after constitution update |\n| `after_specify` | `speckit.git.commit` | Yes | Auto-commit after specification |\n| `after_clarify` | `speckit.git.commit` | Yes | Auto-commit after clarification |\n| `after_plan` | `speckit.git.commit` | Yes | Auto-commit after planning |\n| `after_tasks` | `speckit.git.commit` | Yes | Auto-commit after task generation |\n| `after_implement` | `speckit.git.commit` | Yes | Auto-commit after implementation |\n| `after_checklist` | `speckit.git.commit` | Yes | Auto-commit after checklist |\n| `after_analyze` | `speckit.git.commit` | Yes | Auto-commit after analysis |\n| `after_taskstoissues` | `speckit.git.commit` | Yes | Auto-commit after issue sync |\n\n## Configuration\n\nConfiguration is stored in `.specify/extensions/git/git-config.yml`:\n\n```yaml\n# Branch numbering strategy: \"sequential\" or \"timestamp\"\nbranch_numbering: sequential\n\n# Optional branch name template. Leave empty for the default \"{number}-{slug}\".\n# Supported tokens: {author}, {app}, {number}, {slug}; {slug} must not appear\n# before {number}, and the final path segment must start with {number}-.\n# Example for monorepos: \"{author}/{app}/{number}-{slug}\"\nbranch_template: \"\"\n\n# Optional shorthand namespace. Leave empty to use branch_template/default behavior.\n# Example: \"features/{app}\" expands to \"features/{app}/{number}-{slug}\"\nbranch_prefix: \"\"\n\n# Custom commit message for git init\ninit_commit_message: \"[Spec Kit] Initial commit\"\n\n# Commit message style for auto-commit hooks: \"fixed\" (default) uses the\n# messages below; \"conventional\" asks the agent to generate a Conventional\n# Commit message (e.g. \"feat: add OAuth spec\") from the diff instead.\ncommit_style: fixed\n\n# Auto-commit per command (all disabled by default)\n# Example: enable auto-commit after specify\nauto_commit:\n default: false\n after_specify:\n enabled: true\n message: \"[Spec Kit] Add specification\"\n```\n\n`{author}` is derived from Git config and sanitized for branch names. `{app}` is derived from the Spec Kit init directory name. Custom templates must not put `{slug}` before `{number}`, and must put `{number}-` at the start of the final path segment so generated names remain valid feature branches. For a monorepo project at `apps/web/.specify/`, a template such as `{author}/{app}/{number}-{slug}` produces branches like `jdoe/web/008-guided-tour`.\n\nFor simple namespace-only customization, `branch_prefix` is also accepted as a shorthand and expands to `/{number}-{slug}`.\n\n## Installation\n\n```bash\n# Install the bundled git extension (no network required)\nspecify extension add git\n```\n\n## Disabling\n\n```bash\n# Disable the git extension (spec creation continues without branching)\nspecify extension disable git\n\n# Re-enable it\nspecify extension enable git\n```\n\n## Graceful Degradation\n\nWhen Git is not installed or the directory is not a Git repository:\n- Spec directories are still created under `specs/`\n- Branch creation is skipped with a warning\n- Branch validation is skipped with a warning\n- Remote detection returns empty results\n\n## Scripts\n\nThe extension bundles cross-platform scripts:\n\n- `scripts/bash/create-new-feature-branch.sh` — Bash implementation (branch creation only)\n- `scripts/bash/git-common.sh` — Shared Git utilities (Bash)\n- `scripts/powershell/create-new-feature-branch.ps1` — PowerShell implementation (branch creation only)\n- `scripts/powershell/git-common.ps1` — Shared Git utilities (PowerShell)\n\n\n# GitHub Integration Extension\n\nThis bundled, **opt-in** extension is the home for Spec Kit's GitHub *platform* functionality. Today it provides one command, `speckit.github.taskstoissues`, which turns a feature's `tasks.md` into dependency-ordered GitHub issues.\n\n> NOTE: `git` and `github` are deliberately separate domains. The [`git` extension](../git/README.md) owns local version-control workflow (feature branches, commits, remote detection); this extension owns interactions with the GitHub platform itself.\n\n## Why an extension?\n\nCreating GitHub issues is provider-specific project management, not part of the provider-neutral Spec-Driven Development lifecycle. Keeping it in a dedicated, opt-in extension lets users:\n\n- **Choose whether to install it at all** — `specify init` does **not** install it.\n- **Use a different issue tracker** without having to work around a GitHub-specific core command.\n- **Depend on a stable, namespaced command** from other extensions.\n\n## Installation\n\nFrom the root of an initialized Spec Kit project:\n\n```bash\nspecify extension add github\n```\n\nThe `generic` (bring your own agent) integration registers this command under\nits configured `--commands-dir` in both commands and skills layouts. Installing\n`github` creates `speckit.github.taskstoissues.md` in commands mode or\n`speckit-github-taskstoissues/SKILL.md` in skills mode. The core\n`speckit.taskstoissues` command is deprecated but remains available during migration.\nUse this extension's recommended command instead. See\n[integration-specific options](../../docs/integrations/cli.md#integration-specific-options).\n\n## Removal\n\n```bash\nspecify extension remove github\n```\n\n## Commands\n\n| Command | Description |\n| ------------------------------ | -------------------------------------------------------------------- |\n| `speckit.github.taskstoissues` | Recommended: convert tasks from `tasks.md` into dependency-ordered GitHub issues. |\n\n> NOTE: The command ID above is canonical. Invoke it using the syntax for your integration: `/speckit.github.taskstoissues` for dot-command integrations; `/speckit-github-taskstoissues` for slash-hyphen integrations (including Forge and Cline); `$speckit-github-taskstoissues` for Codex, ZCode, or Command Code in skills mode; or `/skill:speckit-github-taskstoissues` for Kimi.\n\n### What the command does\n\n1. Resolves the active feature and loads its `tasks.md` (via this extension's own `resolve-tasks` script — see [Scripts](#scripts)).\n2. Reads the Git remote and **stops unless it points at GitHub**.\n3. Lists existing repository issues — open *and* closed — and matches their titles against the task IDs in `tasks.md` (`\\bT\\d{3,}\\b`, so four-digit and longer IDs are handled).\n4. Creates issues titled `T001: ` only for task IDs that do not already have one, in the repository identified by the remote.\n\n## Hooks\n\nThis extension consumes the existing `before_taskstoissues` and `after_taskstoissues` hook points, which are read from `.specify/extensions.yml` at run time. The hook keys are unchanged from the core command, so hooks registered by other extensions — for example the `git` extension's auto-commit hooks — keep firing exactly as before.\n\n## Requirements\n\n- Spec Kit **0.12.17 or newer**. Extension-local `scripts/...` path rewriting arrived in\n 0.12.6, but auto-registered skills did not resolve `__SPECKIT_COMMAND_*__` references\n until 0.12.17. Earlier releases cannot render this command correctly in every supported\n layout, so `specify extension add github` refuses to install below 0.12.17.\n- A Git remote pointing at GitHub.\n- The **GitHub MCP server** available to your coding agent, providing the `list_issues` and `issue_write` tools.\n\n> NOTE: Agents without MCP support (for example the Pi Coding Agent out of the box) cannot run this command as intended.\n\n## Scripts\n\nThe extension ships its own feature-resolution script in all three supported runtimes, so it is self-contained and does not reach into core:\n\n| Runtime | Script |\n| ---------- | ---------------------------------------- |\n| Bash | `scripts/bash/resolve-tasks.sh` |\n| PowerShell | `scripts/powershell/resolve-tasks.ps1` |\n| Python | `scripts/python/resolve_tasks.py` |\n\nOnce installed they live under `.specify/extensions/github/scripts/`. The script is a trimmed twin of core's `check-prerequisites`: it resolves the project root and active feature directory, requires `plan.md` and `tasks.md`, and reports the design docs alongside them. It matches the invocation the core command makes (`--require-tasks --include-tasks`), so `spec.md` stays optional. By default, a `SPECIFY_FEATURE_DIRECTORY` override is persisted to `.specify/feature.json` so a later run without the variable resolves to the same feature. When `SPECIFY_FEATURE_NO_PERSIST=1` or `true`, the override still selects the feature for this run, but the script does not create or modify `feature.json`.\n\nPrerequisite errors name the Spec Kit command without assuming an integration's invocation syntax. Use the syntax described under [Commands](#commands) for your integration.\n\n## Migrating from the core `taskstoissues` command\n\nSpec Kit is moving GitHub issue tracking out of core in three stages:\n\n1. **Initial stage (completed)** — this extension shipped with the core `/speckit.taskstoissues` command still available.\n2. **Next (current stage)** — the replacement has been available for at least one release, so the core command is now deprecated. It displays a migration warning and continues its existing workflow. It does not install or enable the extension automatically or run the replacement command.\n3. **Later** — the core command will be removed in a future minor release.\n\nFor existing projects, upgrading the CLI alone does not refresh the generated\ncore command files. After upgrading the CLI, run this from the project root:\n\n```bash\nspecify integration upgrade \n```\n\nReplace `` with the installed integration key, or omit it to upgrade the\ndefault integration. This refreshes the core command with the deprecation\nwarning. If locally modified files block the upgrade, inspect those changes\nbefore deciding whether to overwrite them. See [Upgrade an Integration](../../docs/integrations/cli.md#upgrade-an-integration).\n\nTo migrate, install the extension and use the namespaced command instead:\n\n```bash\nspecify extension add github\n```\n\nThe `generic` integration supports this migration in both commands and skills\nlayouts under its configured `--commands-dir`. The core command remains\navailable during this deprecation period until the removal stage.\n\n| Deprecated core command | Recommended extension command |\n| ------------------------- | --------------------------------- |\n| `/speckit.taskstoissues` | `/speckit.github.taskstoissues` |\n\nApart 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.\n\n### Presets and dependent extensions\n\nBefore the core command is removed, audit references to `speckit.taskstoissues`\nin presets, extension prompts, workflow steps, handoffs, and project automation.\nFor GitHub issue conversion, use the canonical `speckit.github.taskstoissues`\ncommand ID and render it with the agent-specific syntax under [Commands](#commands).\nReplace `__SPECKIT_COMMAND_TASKSTOISSUES__` cross-command references with\n`__SPECKIT_COMMAND_GITHUB_TASKSTOISSUES__` where template rendering is supported.\nDocument `specify extension add github` as a setup prerequisite; the deprecation\nwarning does not install this dependency.\n\nIf an extension proposal or external dependency declaration uses\n`requires.commands: [speckit.taskstoissues]`, update its target to\n`speckit.github.taskstoissues`. `requires.commands` is not an enforced dependency\nfield in the current extension manifest API, so do not rely on that declaration\nto install or check the GitHub extension. Follow the supported requirements in\nthe [extension API reference](../EXTENSION-API-REFERENCE.md#extension-manifest).\n\nPreset command overrides are separate from command references: an override of\n`speckit.taskstoissues` does not automatically customize the namespaced GitHub\ncommand. Review and port any needed customization, then verify the installed\ncommand in a sample project before retiring the old override. A preset that\nuses another issue tracker should retain its own provider-specific workflow\nrather than redirecting it to the GitHub command. Existing overrides may also\nhide the core deprecation warning, so communicate the migration to their users.\n\nKeep the `before_taskstoissues` and `after_taskstoissues` hook keys unchanged;\nboth commands consume them. Only update a hook's command reference if it invokes\nthe deprecated command. Do not invoke both core and replacement commands for\nthe same conversion, since that also runs their hooks twice. Publish and test\nupdated preset/extension versions before the later core-removal release.\n\n\n# Spec Kit Extensions\n\nExtension system for [Spec Kit](https://github.com/github/spec-kit) - add new functionality without bloating the core framework.\n\n## Extension Catalogs\n\nSpec Kit provides two catalog files with different purposes:\n\n### Your Catalog (`catalog.json`)\n\n- **Purpose**: Default upstream catalog of extensions used by the Spec Kit CLI\n- **Default State**: Empty by design in the upstream project - you or your organization populate a fork/copy with extensions you trust\n- **Location (upstream)**: `extensions/catalog.json` in the GitHub-hosted spec-kit repo\n- **CLI Default**: The `specify extension` commands use the upstream catalog URL by default, unless overridden\n- **Org Catalog**: Point `SPECKIT_CATALOG_URL` at your organization's fork or hosted catalog JSON to use it instead of the upstream default\n- **Customization**: Copy entries from the community catalog into your org catalog, or add your own extensions directly\n\n**Example override:**\n```bash\n# Override the default upstream catalog with your organization's catalog\nexport SPECKIT_CATALOG_URL=\"https://your-org.com/spec-kit/catalog.json\"\nspecify extension search # Now uses your organization's catalog instead of the upstream default\n```\n\n### Community Reference Catalog (`catalog.community.json`)\n\n> [!NOTE]\n> Community extensions are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the extension code itself**. Review extension source code before installation and use at your own discretion.\n\n- **Purpose**: Browse available community-contributed extensions\n- **Status**: Active - contains extensions submitted by the community\n- **Location**: `extensions/catalog.community.json`\n- **Usage**: Reference catalog for discovering available extensions\n- **Submission**: Open to community contributions via [issue template](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml)\n\n**How It Works:**\n\n## Making Extensions Available\n\nYou control which extensions your team can discover and install:\n\n### Option 1: Curated Catalog (Recommended for Organizations)\n\nPopulate your `catalog.json` with approved extensions:\n\n1. **Discover** extensions from various sources:\n - Browse `catalog.community.json` for community extensions\n - Find private/internal extensions in your organization's repos\n - Discover extensions from trusted third parties\n2. **Review** extensions and choose which ones you want to make available\n3. **Add** those extension entries to your own `catalog.json`\n4. **Team members** can now discover and install them:\n - `specify extension search` shows your curated catalog\n - `specify extension add ` installs from your catalog\n\n**Benefits**: Full control over available extensions, team consistency, organizational approval workflow\n\n**Example**: Copy an entry from `catalog.community.json` to your `catalog.json`, then your team can discover and install it by name.\n\n### Option 2: Direct URLs (For Ad-hoc Use)\n\nSkip catalog curation - team members install directly using URLs:\n\n```bash\nspecify extension add --from https://github.com/org/spec-kit-ext/archive/refs/tags/v1.0.0.zip\n```\n\n**Benefits**: Quick for one-off testing or private extensions\n\n**Tradeoff**: Extensions installed this way won't appear in `specify extension search` for other team members unless you also add them to your `catalog.json`.\n\n## Available Community Extensions\n\n> [!NOTE]\n> Community extensions are independently created and maintained by their respective authors. Maintainers only verify that catalog entries are complete and correctly formatted — they do **not review, audit, endorse, or support the extension code itself**. The Community Extensions website is also a third-party resource. Review extension source code before installation and use at your own discretion.\n\n🔍 **Browse and search community extensions on the [Community Extensions website](https://speckit-community.github.io/extensions/).**\n\nSee the [Community Extensions](https://github.github.io/spec-kit/community/extensions.html) page for the full list of available community-contributed extensions.\n\nFor the raw catalog data, see [`catalog.community.json`](catalog.community.json).\n\n\n## Adding Your Extension\n\n### Submission Process\n\nTo add your extension to the community catalog:\n\n1. **Prepare your extension** following the [Extension Development Guide](EXTENSION-DEVELOPMENT-GUIDE.md)\n2. **Create a GitHub release** for your extension\n3. **File an issue** using the [Extension Submission](https://github.com/github/spec-kit/issues/new?template=extension_submission.yml) template with all required metadata\n4. **Wait for review** — a maintainer will review the submission, update the catalog, and close the issue\n\nSee the [Extension Publishing Guide](EXTENSION-PUBLISHING-GUIDE.md) for detailed step-by-step instructions.\n\n### Submission Checklist\n\nBefore submitting, ensure:\n\n- ✅ Valid `extension.yml` manifest\n- ✅ Complete README with installation and usage instructions\n- ✅ LICENSE file included\n- ✅ GitHub release created with semantic version (e.g., v1.0.0)\n- ✅ Extension tested on a real project\n- ✅ All commands working as documented\n\n## Installing Extensions\nOnce extensions are available (either in your catalog or via direct URL), install them:\n\n```bash\n# From your curated catalog (by name)\nspecify extension search # See what's in your catalog\nspecify extension add # Install by name\n\n# Direct from URL (bypasses catalog)\nspecify extension add --from https://github.com///archive/refs/tags/.zip\n\n# List installed extensions\nspecify extension list\n```\n\nFor more information, see the [Extension User Guide](EXTENSION-USER-GUIDE.md).\n\n\n# Extension Template\n\nStarter template for creating a Spec Kit extension.\n\n## Quick Start\n\n1. **Copy this template**:\n\n ```bash\n cp -r extensions/template my-extension\n cd my-extension\n ```\n\n2. **Customize `extension.yml`**:\n - Change extension ID, name, description\n - Update author and repository\n - Define your commands\n\n3. **Create commands**:\n - Add command files in `commands/` directory\n - Use Markdown format with YAML frontmatter\n\n4. **Create config template**:\n - Define configuration options\n - Document all settings\n\n5. **Write documentation**:\n - Update README.md with usage instructions\n - Add examples\n\n6. **Test locally**:\n\n ```bash\n cd /path/to/spec-kit-project\n specify extension add --dev /path/to/my-extension\n ```\n\n7. **Publish** (optional):\n - Create GitHub repository\n - Create release\n - Submit to catalog (see EXTENSION-PUBLISHING-GUIDE.md)\n\n## Files in This Template\n\n- `extension.yml` - Extension manifest (CUSTOMIZE THIS)\n- `config-template.yml` - Configuration template (CUSTOMIZE THIS)\n- `commands/example.md` - Example command (REPLACE THIS)\n- `README.md` - Extension documentation (REPLACE THIS)\n- `LICENSE` - MIT License (REVIEW THIS)\n- `CHANGELOG.md` - Version history (UPDATE THIS)\n- `.gitignore` - Git ignore rules\n\n## Customization Checklist\n\n- [ ] Update `extension.yml` with your extension details\n- [ ] Change extension ID to your extension name\n- [ ] Update author information\n- [ ] Define your commands\n- [ ] Create command files in `commands/`\n- [ ] Update config template\n- [ ] Write README with usage instructions\n- [ ] Add examples\n- [ ] Update LICENSE if needed\n- [ ] Test extension locally\n- [ ] Create git repository\n- [ ] Create first release\n\n## Need Help?\n\n- **Development Guide**: See EXTENSION-DEVELOPMENT-GUIDE.md\n- **API Reference**: See EXTENSION-API-REFERENCE.md\n- **Publishing Guide**: See EXTENSION-PUBLISHING-GUIDE.md\n- **User Guide**: See EXTENSION-USER-GUIDE.md\n\n## Template Version\n\n- Version: 1.0.0\n- Last Updated: 2026-01-28\n- Compatible with Spec Kit: >=0.1.0\n"}