* docs: reframe SDD positioning, modernize install, and de-duplicate walkthroughs
Reframe the landing page so Spec Kit reads as a toolkit for Spec-Driven
Development *or your own process* with any AI coding agent, and correct
stale claims: context files and git are now opt-in extensions, and the
install path uses PyPI (specify-cli). Generalize the landing cards to
cover bundles and catalog hosting across all primitives.
Restructure the Quick Start into a lean, guided Taskify walkthrough with
one command per step (install as a prerequisite, Steps 1-9 aligned with
the Full path), and extract the deep per-command detail into two new
reference pages: reference/agentic-sdd.md (the /speckit.* SDD process)
and reference/agentic-bugfix.md (the bug extension). Retitle the
reference overview to "Reference" and group these agentic processes in
their own section, distinct from CLI-managed primitives.
Remove the duplicated "Detailed Process" walkthrough from README.md
(and its TOC entry), repointing readers to the docs-site Quick Start
while keeping the concise "Get Started" section as the front door.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9d9232f8-ece4-4aa6-a9bd-ff8d74ca1c89
* docs: address review feedback on accuracy and scope
- quickstart: correct the git/feature note — resolution reads
.specify/feature.json / SPECIFY_FEATURE, not the checked-out branch,
so switching branches alone does not switch the active feature.
- quickstart + agentic-sdd: add an invocation-style note ($speckit-* for
Codex/ZCode, /skill:speckit-* for Kimi) so the agent-neutral commands
are executable everywhere.
- agentic-sdd: fix the tasks phase structure to match the generator
(Setup, Foundational, one phase per user story, final Polish; tests
optional within user-story phases).
- index: soften the catalog claim (catalogs curate discovery, not an
install allow-list) and relabel the "CLI reference" link to "Reference"
to match the retitled, broader page.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9d9232f8-ece4-4aa6-a9bd-ff8d74ca1c89
* docs: correct feature-resolution override and add bug-command invocation note
- quickstart: the previous fix named the wrong override. The active
feature *directory* resolves from SPECIFY_FEATURE_DIRECTORY then
.specify/feature.json; SPECIFY_FEATURE only supplies the identifier
after a directory is resolved. Rewrite the note to point users at
.specify/feature.json / SPECIFY_FEATURE_DIRECTORY, and clarify the git
extension's branches don't by themselves change the active feature.
- agentic-bugfix: add the same invocation-style caveat as the SDD
reference ($speckit-bug-* for Codex/ZCode, /skill:speckit-bug-* for
Kimi).
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9d9232f8-ece4-4aa6-a9bd-ff8d74ca1c89
* docs: tighten bug-command contracts and drop numbered-phase examples
- agentic-bugfix: don't overstate overwrite protection — an interactive
run can overwrite an existing assessment after confirmation; only
automated mode refuses and picks a new slug. Correct the verify verdict
to the schema's verified/partial/failed (not-run is a per-check status);
an unexercised reproduction downgrades the result to partial.
- agentic-sdd: the implement examples labeled scoping "Phase 1/2", but
the tasks contract reserves Phase 1 for Setup and Phase 2 for
Foundational (user stories start at Phase 3). Scope by phase name and
user-story content instead to avoid mis-scoping execution.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9d9232f8-ece4-4aa6-a9bd-ff8d74ca1c89
---------
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* docs: add PyPI as second supported install route (#3425)
The specify-cli package is now officially published to PyPI via the
publish-pypi.yml trusted-publishing workflow. Document PyPI as a
supported install route alongside the GitHub source install:
- Revise the outdated "not affiliated" warning in installation.md to
reflect that specify-cli on PyPI is an official, maintained channel.
- Add an "Install from PyPI" section and list PyPI under alternative
package managers.
- Add a dedicated docs/install/pypi.md guide (install, pin version,
verify, upgrade, uninstall).
- Add the PyPI guide to the docs TOC.
- Mention the PyPI route in the README quick start.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* docs: refine PyPI install guidance from review (#3516)
Address review feedback for the PyPI install documentation:
- Reword the verification guidance so `specify version` is described as a
local version/runtime check rather than proof of package provenance.
- Clarify that upgrading a pinned `uv tool` install to the newest PyPI
release requires an unpinned reinstall command.
- Note that `specify self upgrade` rebuilds `uv tool` and `pipx`
installs from the GitHub source release URL rather than preserving a
PyPI-based installation.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* docs: clarify PyPI verification and upgrade guidance
Assisted-by: GitHub Copilot (model: MAI-Code-1-Flash, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* docs: point PyPI provenance check to source metadata
Address review feedback: version/list commands do not reveal install
provenance. Direct readers to the source metadata their package manager
records (pipx list --json, PEP 610 direct_url.json) to confirm whether an
install came from PyPI or a Git URL, and note pip show cannot see
uv/pipx-managed environments.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
docs/reference/bundles.md and docs/reference/authentication.md exist on
disk but were absent from the Reference section of docs/toc.yml, so both
pages were orphaned and undiscoverable in the published docs sidebar.
Add the two nav entries (Bundles after Workflows, matching the ordering
in reference/overview.md; Authentication last).
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
* docs: add guide for handling complex features
Add a Concepts page documenting strategies for dealing with large or
complex features where context window exhaustion degrades agent
performance during implementation. Covers limiting tasks per run,
sub-agent delegation, combining both, and decomposing into smaller
specs, with a guideline table for choosing an approach.
Closes#2986
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* docs: address review feedback on complex features guide
Use task IDs (T001-T010) instead of bare numbers to match the tasks.md
template format, and add the combined scoping + delegation approach to
the selection table for completeness.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* docs: align complex features guide with command naming conventions
Use the full /speckit.implement command name throughout, match the
command template wording ('must consider'), and use the product names
GitHub Copilot CLI and the GitHub Copilot extension for VS Code.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Manfred Riem <mnriem@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Shorten README.md install section to single uv command + link to
installation guide for alternatives and troubleshooting
- Add explicit 'Initialize a project' step to README Get Started
- Remove duplicate Troubleshooting section from README
- Reorder 'Make it your own' card on docs landing page so extensions
and presets are explained before the stats
- Update Community nav-card to link to new community overview
- Create docs/community/overview.md landing page (aligned with
reference/overview.md)
- Create dedicated install sub-pages: pipx, one-time (uvx), air-gapped
- Update docs/installation.md to lead with persistent uv install and
link to sub-pages instead of duplicating content
- Update docs/toc.yml with new pages
- Remove stale EOF file
* Add Agent Governance extension to community catalog
Add agent-governance extension submitted by @bigsmartben to:
- extensions/catalog.community.json (alphabetical order)
- README.md community extensions table
Closes#2552
* Move community extensions table from README to docs site
- Create docs/community/extensions.md with full extensions table
- Replace ~120-line table in README.md with summary + link to docs site
- Add Extensions entry to docs/toc.yml under Community
- Update add-community-extension SKILL.md references
Rewrite docs/index.md from a philosophy essay into a landing page
organized around four pillars: Spec-driven by default, Use any coding
agent, Make it your own, and Integrate into your organization.
- Add hero section with GitHub Spec Kit branding and CTA buttons
- Add 2x2 pillar card grid with GitHub Primer color accents
- Add community stats section (96K stars, 200+ contributors, etc.)
- Add navigation cards and footer install CTA
- Move SDD philosophy content to docs/concepts/sdd.md
- Add custom DocFX template overlay with card CSS and dark mode
- Set landing layout for index.md via fileMetadata
- Update toc.yml and docfx.json for new concepts section
Move the community presets table from the main README to a dedicated
docs/community/presets.md page, matching the pattern used for
walkthroughs and friends.
- Add docs/community/presets.md with the full presets table
- Add Claude AskUserQuestion preset (was in catalog but missing from table)
- Add Presets entry to docs/toc.yml under Community
- Replace inline README table with a short link to the docs page
* Move community walkthroughs from README to docs/community
Extract the community walkthroughs section from README.md into its own
docs/community/walkthroughs.md file and replace it with a short summary
linking to the GitHub Pages URL.
* Address review: fix double-See phrasing, add walkthroughs to docs nav
Move the Community Friends section from the main README into a dedicated
docs page at docs/community/friends.md, following the same structure as
the Reference section.
- New: docs/community/friends.md with content from README
- Updated: docs/toc.yml with Community section and Friends entry
- Updated: docs/docfx.json to include community/*.md in content glob
- Updated: README.md to link to the new docs page instead of inline list
* docs: add core commands reference and simplify README CLI section
- New docs/reference/core.md: reference for init (active options only,
copilot as main example), check, and version commands
- docs/toc.yml: add Core Commands under Reference
- README.md: replace verbose CLI Reference section (init options table,
30+ per-agent examples, deprecated flags, env vars) with links to
reference docs; use copilot as main example throughout
* docs: add CLI reference overview page
- New docs/reference/overview.md: explains each CLI surface area
(core, integrations, extensions, presets, workflows) with key
commands and links to detailed reference pages
- docs/toc.yml: add Overview as first item under Reference
- README.md: simplify CLI Reference to single link to overview page
* docs: remove command references from overview, keep paragraphs only
* docs: add workflows reference, reorganize into docs/reference/, and add --version flag
- Move integrations.md, extensions.md, presets.md into docs/reference/
- New docs/reference/workflows.md: command reference for all workflow
commands, built-in SDD Cycle workflow with Mermaid diagram, step types,
expressions, input types, state/resume, and FAQ
- Rename workflow input feature_name to spec with prompt 'Describe what
you want to build' to match speckit.specify command terminology
- Add --version / -V flag to root specify command with tests
- Update docs/toc.yml, README.md links, and docs/upgrade.md cross-reference
to use reference/ paths
- Add workflow command to README CLI reference table
* docs: update speckit_version requirement to >=0.7.2 in workflow example
- New docs/presets.md: command reference for all 9 specify preset commands
and 3 specify preset catalog commands, file resolution stack with Mermaid
diagrams, catalog resolution order, and FAQ
- src/specify_cli/__init__.py: rename pack_id to preset_id across all preset
CLI commands so --help shows PRESET_ID matching the docs
- docs/toc.yml: add Presets under Reference section
- README.md: update presets link to published docs site
- New docs/extensions.md: command reference for all 9 specify extension
commands and 3 specify extension catalog commands, plus catalog
resolution order, extension configuration, and FAQ
- docs/integrations.md: add FAQ section covering single-integration limit,
file preservation, key discovery, CLI vs IDE requirements, upgrade vs switch
- docs/toc.yml: add Extensions under Reference section
- README.md: update integration and extension links to published docs site
- New docs/integrations.md: canonical reference for supported agents table
(with keys), list/install/uninstall/switch/upgrade commands, file
preservation behavior, and integration-specific options
- README.md: replace inline agents table with summary + link to new page;
normalize heading to 'Supported AI Coding Agent Integrations'
- docs/toc.yml: add top-level 'Reference' section with Integrations page
- docs/upgrade.md: fix broken cross-reference, update terminology
- CONTRIBUTING.md: update anchor link to new heading
- Rename docs/upgrading-spec-kit.md to docs/upgrade.md for brevity
- Update README and documentation index links to point to new upgrade guide
- Update table of contents to use shorter "Upgrade" title
- Simplify section headers in upgrade guide
- Add Getting Started section back to docs/index.md with upgrade guide link
Commit-generated-by: GitHub Copilot <github.copilot@github.com>
Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
- Add upgrading-spec-kit.md with detailed upgrade instructions and troubleshooting
- Update table of contents to include upgrading guide in Getting Started section
- Update documentation index and README links
- Address user questions about updating initialized projects from GitHub discussions
Co-authored-by: GitHub Copilot <github.copilot@github.com>
Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
