* docs(scripts): document the 'py' script type and sh/ps migration plan (#3284)
Bring remaining docs up to date with the Python (`py`) workflow-script
variant introduced in #3277, and record the retention/deprecation plan
for the shell variants.
- AGENTS.md: document the `scripts:` frontmatter (sh/ps/py), clarify the
`{SCRIPT}` placeholder resolution, and add a "Script Types and
Migration" section (why py is recommended, defaults, phased sh/ps
deprecation path). Note the Python agent-context variant.
- docs/quickstart.md, docs/local-development.md: mention the `py` variant
and `--script sh|ps|py`.
- docs/reference/integrations.md: add `py` to the `--script` rows for
install/switch/upgrade.
- .devcontainer/devcontainer.json: auto-approve `.specify/scripts/python/`.
Closes#3284.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 298d6ec2-a330-49bc-9394-fe2b77f25ff3
* docs(scripts): address review — accurate paths, prompt behavior, scoped py claims
Addresses the review on PR #3653:
- AGENTS.md: fix the agent-context Python path to its real
`extensions/agent-context/scripts/python/` location.
- AGENTS.md: qualify that only templates that invoke a helper script
carry `scripts:` frontmatter (constitution/specify do not).
- AGENTS.md: narrow the availability claim — `py` covers the core
command templates; the bundled extensions ship Python scripts on disk
but their command templates still invoke shell variants, so `--script
py` does not yet route extension commands to Python.
- AGENTS.md / quickstart / local-development: describe the interactive
prompt vs. non-interactive OS default instead of "auto-selects".
- local-development: add `--script py` to the wrong-script-type fix.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 298d6ec2-a330-49bc-9394-fe2b77f25ff3
* docs(scripts): trim deprecation timeline, correct parity/scope claims (review)
Addresses the second review on PR #3653:
- Remove the speculative four-phase deprecation timeline from AGENTS.md.
A forward-looking removal schedule is roadmap content, not contributor
guidance, and its phases lacked an actionable adoption signal. Replace
it with the concrete contributor parity rule plus a one-line
current-posture note pointing removal work to the #3277 epic.
- Stop stating dual-maintenance as already eliminated: reframe "single
source of truth" as the intended direction, noting all three variants
are still maintained in parallel today.
- Correct the parity-coverage claim: Python ports have output-parity
tests where the contract is stdout-based and unit tests elsewhere,
rather than every file being compared to every shell counterpart.
- Scope the `scripts:` frontmatter rule to core command templates and
note the agent-context/git extension templates don't use it yet.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 298d6ec2-a330-49bc-9394-fe2b77f25ff3
---------
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* 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: run /speckit.checklist after /speckit.plan in quickstart
The quickstart workflow showed /speckit.checklist before /speckit.plan,
contradicting the CLI next-steps text (commands/init.py), which lists the
checklist as running after the plan. Per the maintainer on #2816 — "the
docs were actually wrong here ... checklists are meant for after plan" —
align the docs to the CLI: move /speckit.checklist after /speckit.plan in
the workflow diagram, the prose, and both walkthrough step sequences.
Docs-only; no behavior change.
Closes#2606
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: reword checklist as generating quality checklists, not validating directly
Address review: /speckit.checklist generates quality checklists (which then validate the requirements) rather than validating directly, matching the CLI/README phrasing. Preserves the after-plan ordering.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: align checklist wording with CLI next-steps phrasing
Address review: state the checklist's purpose (validate requirements completeness, clarity, and consistency) and anchor it to /speckit.plan as the CLI does, use the plural 'quality checklists', and reword the Taskify step so the spec is validated using the generated checklists.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: replace deprecated --ai flag with --integration in all documentation
Replace all user-facing --ai, --ai-skills, and --ai-commands-dir references
with their modern equivalents:
- --ai <agent> → --integration <agent>
- --ai-skills → --integration-options="--skills"
- --ai-commands-dir <dir> → --integration generic --integration-options="--commands-dir <dir>"
Updated files:
- README.md (~17 occurrences)
- docs/installation.md (~8 occurrences)
- docs/upgrade.md (~11 occurrences)
- docs/local-development.md (~5 occurrences)
- CONTRIBUTING.md (1 occurrence)
- extensions/EXTENSION-USER-GUIDE.md (1 occurrence)
- src/specify_cli/__init__.py (docstring examples and error messages)
Left unchanged:
- CHANGELOG.md (historical record)
- Test files (intentionally exercise deprecated flag path)
- CLI flag implementation (backward compatibility)
Closes#2358
* docs: address review feedback on pre-existing issues
- Fix duplicate copilot example in README.md (replace with codex)
- Fix invalid gemini --integration-options="--skills" example (gemini
does not support --skills)
- Update generic integration comment from 'Unsupported agent' to
'Bring your own agent; requires --commands-dir'
- Clarify EXTENSION-USER-GUIDE.md: skills auto-register for
skills-based integrations, not only with --integration-options
* docs: replace bare 'AI agent' / 'AI assistant' with 'coding agent' throughout
Full sweep across all documentation and user-facing CLI messages to
align terminology. Bare references like 'AI agent', 'AI assistant',
and 'AI Agent' are replaced with 'coding agent' or 'coding agent
integration' as appropriate.
Intentionally left unchanged:
- 'AI coding agent' (already correct expanded form)
- Deprecated --ai flag help text and error messages (describes the
deprecated flag itself)
- Community extension descriptions (external project text)
- 'generated by an AI' in CONTRIBUTING.md (general AI, not agent)
* docs: address review — remove deprecated --offline, qualify --skills scope
- Remove --offline from docstring examples (deprecated no-op)
- Remove --offline from CONTRIBUTING.md testing example
- Replace --offline instructions in docs/installation.md with note that
bundled assets are used by default
- Qualify --integration-options="--skills" in README.md to note it only
applies to integrations that support skills mode
* docs(install): add pipx as alternative installation method
- Add pipx commands to README.md installation section
- Add note about pipx compatibility to docs/installation.md
- Mention pipx persistent installation in docs/quickstart.md
- Add pipx upgrade instructions to docs/upgrade.md
- Clarify that project has no uv-specific dependencies
Refs: https://github.com/github/spec-kit/discussions/2255
* docs(install): address Copilot feedback - update prerequisites and upgrade references for pipx
* Update docs/quickstart.md
markdownlint’s MD012 (enabled in this repo) flags multiple consecutive blank lines
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
* Update docs/upgrade.md
In the Quick Reference table, the label “pipx upgrade” is misleading because the command shown is `pipx install --force ...` (a reinstall). by copilot.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
- Convert blockquotes to GFM admonitions for better visibility
- Add current directory initialization example
- Expand process to 6 steps with clarify, analyze, checklist, implement
- Update example with separate clarify commands
- Add proper links in Next Steps
Fixes#906, #472
Generated-by: GitHub Copilot <github.copilot@github.com>
Signed-off-by: Ashley Childress <6563688+anchildress1@users.noreply.github.com>
Add automated markdown linting to ensure consistent formatting across
all markdown files in the repository.
Changes:
- Add .markdownlint-cli2.jsonc configuration
- Create .github/workflows/lint.yml for CI/CD integration
- Fix all 908 existing markdown errors across 27 files
- Enforce ATX-style headings and asterisk emphasis
- Set consistent 2-space list indentation
This prevents markdown errors after project initialization and
maintains high documentation quality standards.
