* docs(integrations): document the 'integration list --catalog' flag
'specify integration list' accepts a --catalog flag (integrations/_query_commands.py:
typer.Option(False, "--catalog", ...)) that browses the full built-in +
community catalog, but the Integrations reference documented no options for the
list command. Add an option table for it, matching the style used by the sibling
'integration search' and 'integration catalog add' sections.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs(integrations): clarify that default 'integration list' shows only built-ins
The --catalog row implied the default list already includes the full installed
set; in fact 'integration list' iterates INTEGRATION_REGISTRY (built-ins) and
marks installed status, so a community integration that is not built in only
appears with --catalog. Reword the option and the intro sentence to say the
default shows the built-in integrations and --catalog adds community ones.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
`FanInStep.execute` already guards a non-list `wait_for` (#3482), and the
engine's load-time validation rejects non-string entries. But the engine does
not auto-validate step config, so on an unvalidated run `execute` iterated the
list's *elements* raw:
- An unhashable entry (a list/dict from a YAML indentation slip like
`wait_for: [[a, b]]`) crashed the whole run at `context.steps.get(entry, ...)`
with a raw `TypeError: cannot use 'list' as a dict key`.
- A hashable-but-non-string entry (`wait_for: [123]`) silently joined an empty
`{}` and still reported COMPLETED — the exact "silent empty result +
COMPLETED" wiring bug the whole-list guard and the engine's fan-in
validation both exist to prevent.
Extend the execute() guard to reject any non-string entry with the engine's
"entries must be step-id strings" phrasing, mirroring the sibling non-list
guard right above it. Adds regression coverage for unhashable and
hashable-non-string entries.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(workflows): fail fan-out loudly on a truthy non-mapping step template
A fan-out step whose `step:` is a truthy scalar or list (an authoring mistake) passed execute and reached the engine, which calls template.get("id", ...) in _run_fan_out — raising AttributeError and taking down the whole run. validate already rejects a non-mapping step, but the engine does not auto-validate, so an unvalidated run crashed.
Guard execute to FAIL the step (with a clear error and normalized empty output) instead, mirroring the existing non-list items guard and the switch non-dict cases guard. Add the matching test_execute_non_dict_step_fails_loudly covering the execute-path guard (validate was already covered).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(workflows): reject explicit fan-out `step: null` in validate()
The runtime guard in execute() rejects a truthy non-mapping step, but
`config.get("step", {})` only substitutes the `{}` default for an *absent*
key — an explicit `step: null` reaches the guard as None and FAILS the step.
validate() previously exempted None (`step is not None and ...`), so such a
workflow passed validation and then failed during execution.
Align validate() with the runtime guard: a present-but-non-mapping `step`
(including `None`) is an authoring mistake and is now rejected up front.
Extend the validate and execute regression cases to cover None.
Addresses Copilot review feedback on #3537.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
`PromptStep.execute` str()-coerces `config['prompt']` and dispatches the
result to the integration CLI as the model's instructions. But its `validate`
only checked that `prompt` was *present*, not that it was a string — the exact
parity gap the sibling `ShellStep` closes for `run`.
So a YAML authoring slip like `prompt: [review, this]` or `prompt:` (null)
passed validation, then `execute` sent the Python repr (`"['review', 'this']"`,
`"None"`) to the LLM verbatim — silently wrong instructions with no error and a
COMPLETED status. The engine does not auto-validate step config
(`load_workflow` explicitly defers validation), so validation is the only place
this surfaces before dispatch.
Extend `validate` to reject any non-string `prompt` with the shell-step's
phrasing ("'prompt' must be a string, got <type>"), mirroring the shell `run`
and command `input`/`options` type checks. A `{{ ... }}` expression is still a
str, so it stays valid. Adds regression coverage for non-string prompts
(null/list/int/dict) and confirms an expression prompt still validates.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(workflows): route 'workflow status --json' errors to stderr
The workflow_status run_id error paths (FileNotFoundError -> 'Run not found',
ValueError -> invalid run) used the stdout console and fired before the
json_output branch, so 'specify workflow status <bad-id> --json' wrote a
Rich-rendered error to stdout and corrupted the JSON stream a consumer would
json.loads(). Route both through _error_console(json_output) so they go to
stderr under --json, matching the sibling 'workflow run'/'workflow resume'
commands (which use the identical RunState.load try/except) and the documented
stdout-purity contract.
Test asserts the not-found error appears on stderr and stdout stays empty under
--json (fails before: the error was on stdout).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* test(workflows): cover the ValueError handler in workflow status --json purity
The stderr-routing fix reroutes both the FileNotFoundError and ValueError run_id
handlers, but the test only exercised FileNotFoundError — a regression of the
ValueError path back to stdout would have gone uncaught. Add a ValueError case
(RunState.load raising) asserting the same stderr-only / empty-stdout behavior.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Forge installs its slash-commands with hyphenated names (speckit-foo-bar, via
format_forge_command_name and the injected frontmatter name), but
ForgeIntegration inherited MarkdownIntegration.build_command_invocation, which
builds the dotted /speckit.<cmd>. So 'workflow'/command dispatch invoked
/speckit.plan while the registered command is /speckit-plan — a name Forge never
registered.
Override build_command_invocation to reuse format_forge_command_name, producing
/speckit-<name> (with '.'-to-'-' for extension commands), mirroring the skills
agents' hyphenated invocation.
Tests assert Forge core + extension invocations are hyphenated, incl. args
(fail before: dotted /speckit.plan / /speckit.git.commit).
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* chore: bump version to 0.13.0
* chore: begin 0.13.1.dev0 development
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
_acquire_via_az_cli runs 'az account get-access-token' with text=True, so
subprocess.run decodes stdout with the locale encoding and raises
UnicodeDecodeError (a ValueError sibling, NOT a JSONDecodeError) when the output
can't be decoded. That escaped the except (OSError, TimeoutExpired,
JSONDecodeError, KeyError) tuple and crashed a helper whose contract is to
return str | None. Add UnicodeDecodeError to the tuple.
Test patches subprocess.run to raise UnicodeDecodeError and asserts resolve_token
returns None (fails before: the error propagated).
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(extensions): add assess idea assessment pipeline extension
Add a role-neutral, opt-in "Idea Assessment Pipeline" extension (id:
assess) covering the discovery work that happens BEFORE spec-driven
development. It provides a five-stage funnel: intake, research, define,
shape, decide, each writing one artifact under
.specify/assessments/<slug>/. A go verdict hands off to
/speckit.specify; killing an idea is a first-class success outcome.
Registration:
- extensions/catalog.json: bundled core opt-in entry (before bug)
- pyproject.toml: force-include maps into core_pack so it ships in the
installed wheel (verified via wheel build)
Also normalizes a Rich-wrapped substring assertion in test_workflows.py
so the suite passes at CI's 80-column non-TTY width.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1f25cf9d-b7eb-4b2b-b811-3e91d8db8f6a
* fix(extensions): address PR review on assess extension
Resolve review feedback on github/spec-kit#3568:
- catalog.json: bump top-level updated_at to this revision (2026-07-17)
- extension.yml + catalog.json: shorten the assess description to under
the documented 200-char manifest limit (kept aligned across both)
- extension.yml: make the before_specify hook prompt condition-neutral
(it fires on every /speckit.specify, so it must not claim "no
assessment found")
- intake.md: fix slug normalization to explicitly allow lowercase
letters a-z (the old rule permitted only digits and '-', contradicting
the offline-mode example)
- intake.md + research.md: require a sanitized source URL (strip
userinfo and credential/signature query params) instead of persisting
a verbatim URL that could leak secrets into project artifacts
- decide.md: remove the "trivially small" exception so a go always
requires a shaped concept, making verdict behavior deterministic and
consistent with the guardrails and README
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1f25cf9d-b7eb-4b2b-b811-3e91d8db8f6a
* refactor(extensions): remove before_specify hook from assess
Assess is a separate business process from spec-driven development, so
it should not inject itself into the /speckit.specify lifecycle. The
hook fired on every /speckit.specify invocation (it had no condition),
nagging even when an assessment already existed and the user was
deliberately proceeding.
Unlike git's before_specify (a mechanical prerequisite: create a feature
branch) or agent-context's after_* hooks (reacting to spec output),
assess is an upstream, optional, human-judgment process. The coupling
that belongs here already runs forward and by choice: a `go` verdict
from /speckit.assess.decide hands off to /speckit.specify. The backward
hook was the redundant, intrusive direction.
- extension.yml: drop the hooks block (commands-only manifest)
- README.md: replace the Hooks section with a Handoff section
- test: replace the hook assertion with test_declares_no_hooks to lock
in the standalone-pipeline design
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1f25cf9d-b7eb-4b2b-b811-3e91d8db8f6a
* fix(extensions): harden assess slug handling and clarify verdict logic
Address the second review round on github/spec-kit#3568:
- Slug path traversal: intake and all four downstream commands
(research, define, shape, decide) now normalize an explicit or
user-supplied slug to the [a-z0-9-] alphabet (dropping '.', '/', '\\')
and reject an empty normalized result before constructing ASSESS_DIR.
This guarantees a slug like `../..` cannot escape .specify/assessments/.
- Metadata accuracy: the extension.yml and catalog.json descriptions no
longer imply a "build/kill" call is handed to /speckit.specify — only a
`go` hands off; a `kill` closes the assessment.
- Verdict determinism (decide): a `go` now explicitly requires evidence
strength `adequate`+ (never weak/unknown), resolving the conflict with
the thin-evidence guardrail.
- Risk polarity (decide): renamed the "Risk" criterion to "Risk posture"
with positive polarity (strong = risks understood and mitigated) so it
composes with the other scores that feed the verdict.
- README: aligned the go-threshold guardrail with the evidence rule and
documented the slug-normalization safety property.
The PR description was also updated to drop the stale before_specify
hook claim (the hook was removed in the previous commit).
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1f25cf9d-b7eb-4b2b-b811-3e91d8db8f6a
* fix(extensions): add symlink/realpath containment and pin research host allowlist
Address the third review round on github/spec-kit#3568:
- Path safety (intake, research, define, shape, decide): slug
normalization blocks lexical `..` but not symlinked path components.
Each command now, before any mkdir/read/write, resolves the real path
of .specify/assessments/<slug>/ and every artifact, refuses to follow a
symlinked .specify / assessments / slug dir / artifact, and verifies the
resolved path stays inside the project root. This blocks a cloned or
crafted project from redirecting reads/writes outside the repository.
Each stage enforces this independently since research/define/decide can
run without intake.
- research URL policy: replaced the open-ended "and comparable well-known
hosts" no-prompt branch with intake's exact enumerated allowlist, so an
agent cannot classify an attacker-controlled host as "comparable" and
fetch it without confirmation.
- README: guardrail now documents symlink/realpath containment.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1f25cf9d-b7eb-4b2b-b811-3e91d8db8f6a
* fix(extensions): redact secrets in captured idea and stop on explicit-slug collision
Address the fourth review round on github/spec-kit#3568 (intake):
- Secret leak in the captured idea: quoting the original "verbatim"
contradicted the URL sanitization rule when the idea itself contained a
credential-bearing URL. Capture now redacts secrets (sanitize URLs;
strip tokens, passwords, keys, cookies) inside the quoted text as well
as the Source field, and the section heading is "Idea (as captured)"
rather than "verbatim".
- Explicit-slug collision: in automated mode an existing intake.md caused
a silent switch to a new slug, contradicting the no-suffix guarantee for
user-provided slugs. Now: user-provided slug collision -> stop and
report; only a self-generated slug (already disambiguated at resolution)
is re-slugged.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1f25cf9d-b7eb-4b2b-b811-3e91d8db8f6a
* fix(extensions): reject IPv6 private ranges and DNS-rebinding in URL policy
Address the remaining open comment from review 4722852090 on
github/spec-kit#3568 (the other six comments in that round were already
resolved by the slug-validation and host-allowlist fixes in 9cd07fb and
c032a2e).
The URL Trust Policy refused only textual IPv4 loopback/RFC1918/metadata
hosts, so an approved hostname resolving to an internal IPv6 or
IPv4-mapped address could still reach internal services. The refuse-
outright list now covers IPv6 link-local (fe80::/10), unique-local
(fc00::/7), IPv4-mapped forms, and the IPv6 metadata address, and adds a
resolution-time check: even an allowlisted or user-confirmed host is
refused when it resolves to any non-public address, defeating DNS
rebinding. Mirrored the summary in research's inherited-policy note.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1f25cf9d-b7eb-4b2b-b811-3e91d8db8f6a
* fix(extensions): pin connection vs DNS rebinding and gate slug-only direct entry
Address the fifth review round on github/spec-kit#3568:
- DNS rebinding (intake + research): a standalone DNS lookup does not
defeat rebinding because the fetch client can re-resolve or pick a
private address from a mixed answer. The policy now requires the fetch
to pin the connection to a validated public address (or verify the
connected peer) and re-apply the refusal ranges to the address actually
connected to; if the fetch mechanism cannot pin or expose the peer, the
fetch is refused rather than trusted by hostname.
- Slug-only direct entry (research + define): when intake/research
artifacts are absent and $ARGUMENTS carries only a slug, the commands no
longer infer an idea/problem from the slug. They now require substantive
idea/problem text and otherwise prompt (interactive) or stop (automated).
- Cleaned up a leftover duplicate ASSESS_DIR assignment line in research.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1f25cf9d-b7eb-4b2b-b811-3e91d8db8f6a
* fix(extensions): allow read-only source inspection in intake guardrail
Address the sixth review round on github/spec-kit#3568.
The intake guardrail said the command "only reads and writes inside
.specify/assessments/<slug>/", which contradicts its documented inputs:
intake must read a codebase pointer (repository inspection) and fetch an
allowed URL to capture the idea. The guardrail now limits only *writes*
to the assessment directory and explicitly permits read-only inspection
of the supplied sources (repo + allowlisted URL fetch under the URL Trust
Policy). The other four commands already phrased this correctly ("read
only, and write inside ...") and are unchanged.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1f25cf9d-b7eb-4b2b-b811-3e91d8db8f6a
* Harden assess commands: ancestor path safety, untrusted-artifact reads, research dir creation
Addresses review 4723905370 on PR #3568 across three themes:
- Ancestor path safety: verify `.specify` and `.specify/assessments` are
real directories (not symlinks) resolving inside the project root before
any filesystem-based slug resolution, in all five commands.
- Untrusted artifact reads: treat the contents of persisted assessment
artifacts (intake/research/problem/concept) as untrusted data, not
instructions — ignore embedded directives, mirroring the URL Trust Policy.
- research now ensures the validated ASSESS_DIR exists before writing, since
it may be the first assessment command run.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1f25cf9d-b7eb-4b2b-b811-3e91d8db8f6a
* Allow absent assessment dir in ancestor path-safety check
Addresses review 4723955260 on PR #3568. The ancestor path-safety clause
required `.specify/assessments` to already be a real directory, which blocked
the first-run commands (intake, research, define) from ever reaching the step
that creates it. Reword the clause in all five commands so a not-yet-created
directory is permitted, while still refusing when `.specify` or
`.specify/assessments` exists as a symlink or escapes the project root.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1f25cf9d-b7eb-4b2b-b811-3e91d8db8f6a
* Fix README diagram: needs-clarification revisits the named earlier stage
Addresses review 4724027270 on PR #3568. The overview flowchart routed every
needs-clarification verdict back to research, but decide.md's Revisit stage can
send an idea back to intake, research, define, or shape. Reroute the arrow as a
generic loop back to the earlier stages so the diagram no longer misstates the
pipeline.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1f25cf9d-b7eb-4b2b-b811-3e91d8db8f6a
* Make decide handoff integration-neutral (no hard-coded dot-style)
Addresses review 4724080304 on PR #3568:
- decide.md frontmatter description hard-coded `/speckit.specify`. Frontmatter
is parsed before command-reference resolution, so it now uses agent-neutral
wording ("hand survivors off into Spec-Driven Development") instead of a
dot-style literal that would be wrong for non-dot integrations.
- The `## If go — Handoff to …` heading inside the decision.md output template
hard-coded `/speckit.specify`, which would be written verbatim into
decision.md. It now uses the `__SPECKIT_COMMAND_SPECIFY__` placeholder, like
the rest of the command, so the active integration's invocation style is
rendered.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1f25cf9d-b7eb-4b2b-b811-3e91d8db8f6a
---------
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
`_download_manifest` and its `_require_https` helper parsed the catalog
entry's `download_url` with an unguarded `urlparse(url)`. A malformed
authority — e.g. an unclosed IPv6 bracket like `https://[::1` — makes
`urlparse` (or `.hostname` on older Pythons) raise a raw `ValueError`. The
three `bundle` CLI commands (`info`, `install`, `update`) only catch
`BundlerError`, so that `ValueError` escaped as an uncaught traceback.
Wrap both parse sites in the same `try/except ValueError -> BundlerError`
guard already used by the sibling `_validate_remote_url` (and established by
the merged catalog-URL fix#3576), so a bad `download_url` reports a clean,
actionable error in every mode.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
`PresetCatalog._validate_catalog_url` called `urlparse(url).hostname` without
guarding it. For a malformed authority such as an unterminated IPv6 bracket
(`https://[::1`), `urlparse(...).hostname` raises `ValueError: Invalid IPv6 URL`,
which escapes the method. Its docstring promises `PresetValidationError`, and its
callers (`preset catalog add`, `preset catalog list` reading the
`SPECKIT_PRESET_CATALOG_URL` env var / `.specify/preset-catalogs.yml`) only catch
`PresetValidationError` -- so a malformed URL crashes the CLI with a traceback
instead of a clean error message.
The shared `CatalogStackBase` (#3435), `workflows` (#3484), `bundler` (#3433) and
`IntegrationCatalog` copies already wrap this in `try/except ValueError`; the
preset validator was the remaining un-updated twin. Mirror the shared
implementation: wrap `urlparse` + `.hostname`, re-raise as
`PresetValidationError("Catalog URL is malformed: ...")`, and read the local
`hostname` in the host check.
Add a regression test mirroring `IntegrationCatalog`'s
`test_malformed_url_rejected_cleanly`; it is red before the fix (raw `ValueError`)
and green after.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* chore(deps): bump github/codeql-action/init from 4.36.2 to 4.37.1
Bumps [github/codeql-action/init](https://github.com/github/codeql-action) from 4.36.2 to 4.37.1.
- [Release notes](https://github.com/github/codeql-action/releases)
- [Changelog](https://github.com/github/codeql-action/blob/main/CHANGELOG.md)
- [Commits](8aad20d150...7188fc3636)
---
updated-dependencies:
- dependency-name: github/codeql-action/init
dependency-version: 4.37.1
dependency-type: direct:production
update-type: version-update:semver-minor
...
Signed-off-by: dependabot[bot] <support@github.com>
* chore(deps): bump github/codeql-action/analyze to 4.37.1
Bump the analyze step to match the init step (both now 7188fc3 / v4.37.1).
Dependabot bumped only init, leaving analyze on 4.36.2, which caused CodeQL
to fail with "Loaded a configuration file for version '4.37.1', but running
version '4.36.2'". Both steps must reference the same release.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
---------
Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: mnriem <mnriem@users.noreply.github.com>
Match the README hero tagline to the docs landing hero and rewrite the
subtitle to reflect the four-pillar positioning (ready-to-use spec-driven
process or bring your own, extensible, community-driven, org-ready) rather
than framing everything around SDD.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Copilot-Session: da32794c-5044-406c-9338-12b3ffab49f4
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* chore: bump version to 0.12.18
* chore: begin 0.12.19.dev0 development
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Reframe the docs landing hero and "Make it your own" pillar to inject
the "harness" and "SDLC" framing while keeping SDD front and center:
- Hero: describe Spec Kit as an extensible, intent-driven harness that
pushes any coding agent beyond code, across the SDLC or any business
process; tagline now contrasts step-by-step vs automated-workflow runs.
- "Make it your own": explain the process lives in swappable building
blocks (not locked to SDD or even software) and add a real non-software
preset (Fiction Book Writing) to back the broadened scope.
- Community blurb: drop "development" so "entirely new processes" matches
the wider positioning.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, supervised)
Copilot-Session: 1cf71797-ac0d-4a5e-8266-784906933b54
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: refresh landing page ecosystem stats
Update stale numbers in docs/index.md to match current catalogs on
upstream/main and live GitHub data: extensions 105->138, presets
22->25, integrations 30+->35, contributors 200+->240+, friends 4->6,
GitHub stars 106K+->121K+, extension authors 60+->70+, and the
last-updated date.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: e5f34221-4e6c-42e8-9fa3-5cfbc26104d1
* docs: align community extension stats on overview page
Update docs/community/overview.md from "Over 90 ... 50+ authors" to
"Over 130 ... 70+ authors" so it matches the refreshed landing-page
numbers in docs/index.md (137 community extensions, 77 unique authors).
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 134166d9-e599-44fa-a88d-daf84ab6aca6
---------
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* chore: bump version to 0.12.17
* chore: begin 0.12.18.dev0 development
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
* fix(workflows): fail if/switch steps on non-list branch instead of crashing
`IfThenStep.validate()` and `SwitchStep.validate()` already reject a
non-list branch (`then`/`else`, and `case`/`default`), but the engine's
`execute()` path does not auto-validate (see
`WorkflowEngine.load_workflow`, whose docstring notes the definition is
"not yet validated"). On an unvalidated run, the selected branch is fed
straight into `next_steps`, which `_execute_steps` iterates as step
mappings. A non-list branch — a single mapping or scalar authoring
mistake — was iterated element-wise (a dict yields its string keys, a
str its characters) and raised `AttributeError` on `.get()`, taking down
the whole run; the engine invokes `step_impl.execute()` with no
surrounding try/except.
Guard both `execute` paths to return a FAILED StepResult naming the type
error instead, mirroring the switch non-mapping `cases` and fan-out
non-list `items` handling. The switch guard is factored into a shared
`_non_list_branch_failure` helper covering both `case` and `default`
branches. A missing `else`/`default` still defaults to an empty list
(COMPLETED), unchanged; the guard fires only on an explicit non-list
value. The condition/expression is still evaluated first, so its result
is surfaced in the step output for downstream context.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* test(workflows): cover switch non-list branch execute paths
Copilot flagged the new switch branch guards as untested: coverage
stopped at a non-mapping `cases` container. Add SwitchStep.execute
tests for a matched case with a non-list body and a non-list default
(dict/str/int), asserting FAILED, the branch-specific error, empty
next_steps, and preserved expression_value. Also add explicit
`default: null` / `else: null` normalization tests so the
validator-approved empty-branch contract cannot regress.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* feat(integrations): add Grok Build skills-based integration
Add first-class support for xAI Grok Build via SkillsIntegration, installing
speckit skills under .grok/skills and wiring init/invocation/catalog surfaces.
Assisted-by: Grok Build (model: grok-4, supervised)
* test+docs: address Copilot review on Grok multi-install and next steps
Assert init next-steps guidance for Grok (.grok/skills, /speckit-*) and
clarify that multi-install safety is path/manifest isolation, not
agent-context defaults such as shared AGENTS.md.
* fix(integrations): Grok headless --always-approve and isolation paths
Document Grok multi-install isolation as .grok/skills and .grok/rules.
Override build_exec_args to pass --always-approve so non-interactive
dispatch is not blocked at tool permission gates.
* docs(integrations): list only managed .grok/skills for Grok isolation
Multi-install isolation documents Spec Kit-managed paths; Grok only
writes .grok/skills, so drop the read-only .grok/rules entry.
* fix(integrations): always-slash Grok hooks and refresh catalog date
Move grok to ALWAYS_SLASH_AGENTS so hooks never emit /speckit.plan when
ai_skills is missing/false. Update slash-format tests, persist ai_skills
on init, and bump catalog updated_at for the Grok entry.
---------
Co-authored-by: Nate Chadwick <1232206+natechadwick@users.noreply.github.com>
Co-authored-by: test <test@example.com>
The bash and Python twins validate --number against ^[0-9]+$ and reject a
negative value with 'Error: --number must be a non-negative integer'. The
PowerShell twin declares the parameter as [long]$Number, so PowerShell binds
'-5' as -5 instead of rejecting it. That value then formats via '{0:000}' to
'-005' and yields a branch name starting with a dash, which git refuses (refs
cannot begin with '-') — a confusing late failure instead of the twins' clear
early error.
Guard for $Number -lt 0 up front (before the description check, matching the
bash twin's parse-time validation order) and emit the identical error. An
explicit -Number 0 is still honored, preserving the #3412 fix.
Add matching negative-number parity tests to the bash and PowerShell
create-feature suites, mirroring the existing test_explicit_number_zero_is_honored
pair. Same PowerShell-parity bug class as #3412.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Fix preset-constitution-not-installed: use PresetResolver in constitution setup
Apply the remediation from the bug assessment on issue #3272.
Changes:
1. Modify ensure_constitution_from_template (init.py) to resolve the
constitution-template through the preset priority stack via
PresetResolver, instead of hardcoding the core template path. This
ensures a preset's replacement constitution-template is used when
seeding .specify/memory/constitution.md.
2. Reorder init flow: move ensure_constitution_from_template to after
the preset installation block so that 'specify init --preset' seeds
the memory file from the already-resolved template stack, not from
the generic template that existed before the preset arrived.
3. Add _maybe_reseed_constitution to PresetManager (presets/__init__.py):
a post-install hook that re-seeds .specify/memory/constitution.md
from the preset's constitution-template during 'specify preset add'
on an existing project, but only when the memory file still contains
generic placeholder tokens ([PROJECT_NAME] or [PRINCIPLE_1_NAME]).
Legitimately authored constitutions (no placeholder tokens) are never
overwritten.
4. Add regression tests covering both code paths (TestConstitutionReseedOnPresetInstall
and TestEnsureConstitutionFromTemplate in tests/test_presets.py).
Refs #3272
Assisted-by: GitHub Copilot (model: claude-sonnet-4.6, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Harden preset constitution resolution
Use manifest-aware composed content, atomic safe writes, and conservative generic-template matching for constitution seeding and re-seeding.
Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 49891a32-bec4-462c-a7f2-6d6ec4eefcdb
* Limit preset CLI change to regression test
Remove accidental whole-file Ruff formatting introduced during conflict resolution so the PR contains only the intended end-to-end test.
Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 49891a32-bec4-462c-a7f2-6d6ec4eefcdb
* Make preset init test depend on init ordering
Disable preset-install lifecycle seeding in the regression test so it fails unless init materializes the constitution after registering the preset.
Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 49891a32-bec4-462c-a7f2-6d6ec4eefcdb
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Ben Buttigieg <70525+BenBtg@users.noreply.github.com>
`specify integration use copilot` against a Copilot install configured with
`--integration-options "--skills"` dropped `"ai_skills": true` from
init-options.json and regenerated extension commands in the legacy
`.agent.md`/`.prompt.md` layout, contradicting `integration.json`'s stored
`parsed_options.skills: true`.
`_update_init_options_for_integration` only inspected `SkillsIntegration` /
the instance `_skills_mode` flag. On the `use` path no `setup()` runs, so the
freshly-resolved Copilot instance has `_skills_mode == False` and the stored
skills intent in `parsed_options` was ignored. Thread the resolved
`parsed_options` through and treat `parsed_options["skills"]` as skills mode.
Adds a regression test that resets the registry singleton's `_skills_mode` to
simulate a fresh process (in-process singleton reuse otherwise masks the bug).
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Copilot-Session: 06fb6ae9-f444-4dfd-ab3f-d0669c5d0604
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* Add Figma Starter extension to community catalog
Add figma-starter extension submitted by @vibhus to:
- extensions/catalog.community.json (alphabetical order)
- docs/community/extensions.md community extensions table
Closes#3545
Assisted-by: GitHub Copilot (model: claude-sonnet-4.6, autonomous)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix: add missing python3 >=3.8 version constraint in figma-starter catalog entry
Assisted-by: GitHub Copilot (model: claude-sonnet-4.5, autonomous)
* fix(agent-context): reduce Python subprocess overhead in PS 5.1 YAML fallback
The PowerShell update-agent-context.ps1 script falls back to Python when
PS 5.1 (which lacks ConvertFrom-Yaml and cannot parse YAML as JSON) reads
the extension config. It previously launched Python twice: once to verify
that Python 3 + PyYAML were available, and once to run a temp script file
that parsed the YAML and printed JSON.
On Windows CI each Python startup—plus potential Windows Defender scanning
of a freshly-created .tmp file—can take several seconds. With two launches
plus PS 5.1's own startup time the subprocess.run(timeout=30) threshold in
test_powershell_script_discovers_nested_plan was regularly exceeded, causing
the CI job to fail.
Replace the two-phase approach with a single Python -c one-liner that
verifies PyYAML availability, parses the YAML file, and emits JSON in one
process. This halves the number of Python launches and eliminates the temp
file entirely, keeping total execution time well under 30 s.
Assisted-by: GitHub Copilot (model: claude-sonnet-4.5, autonomous)
* revert(agent-context): restore update-agent-context.ps1 to pre-optimization state
The runtime optimization (one-liner Python fallback, stderr suppression) was
unrelated to the Figma Starter catalog addition (issue #3545) and removed the
actionable PyYAML/parse diagnostic messages. Revert the file so the PR only
contains the catalog-entry and documentation changes.
Assisted-by: GitHub Copilot (model: claude-sonnet-4.6, autonomous)
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
* chore: bump version to 0.12.16
* chore: begin 0.12.17.dev0 development
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
The `map`, `join`, and `contains` expression filters assumed their
argument was a string. A non-string argument — an authoring mistake such
as `| map(5)`, `| join(5)`, or `| contains(5)` — reached an operation
that only strings support and raised a cryptic exception that escaped the
evaluator entirely:
* `map(5)` -> `attr.split(".")` -> AttributeError
* `join(5)` -> `separator.join(...)` -> AttributeError
* `contains(5)` on a string value -> `x in str` -> TypeError
The engine wraps neither expression evaluation nor `step_impl.execute()`
in a try/except, so each of these took down the whole run with a message
that names none of the real problem.
Validate the argument type up front and raise a `ValueError` naming the
filter and the offending type instead, mirroring the strict argument
handling already in `from_json`. `contains` guards only the string-value
branch: for a list value, membership of any element type is legitimate
(`5 in [1, 2, 5]`), so that branch is intentionally left unguarded.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(workflows): expose workflow source directory to steps (#3467)
Propagate WorkflowDefinition.source_path to steps via
{{ context.workflow_dir }} in template expressions and
SPECKIT_WORKFLOW_DIR env var for shell steps. The original
source directory is persisted in state.json so resume
restores the correct value instead of the run-directory copy path.
Closes#3467
Assisted-By: 🤖 Claude Code
* fix: apply bot review suggestions (#2)
Applied fixes from bot review comments:
- Comment #3563319058: prevent stale SPECKIT_WORKFLOW_DIR leak from parent env
- Comment #3563319094: use cross-platform Python one-liner instead of printenv
- Comment #3563319103: add monkeypatch.delenv for deterministic env var test
- Comment #3563319116: same env leak fix as #3563319058
Assisted-By: 🤖 Claude Code
* fix: use YAML single-quotes and forward-slash paths for Windows CI (#2)
sys.executable on Windows returns backslash paths (D:\a\...) which YAML
double-quoted strings interpret as escape sequences. Switch to
single-quoted YAML strings and normalize paths with replace("\\", "/").
Assisted-By: 🤖 Claude Code
* fix: resolve workflow_dir to absolute path and add installed-by-ID test (#3469)
Applied fixes from bot review comments:
- Comment #3563382853: resolve source_path before taking parent to ensure absolute paths
- Comment #3563382864: add test for installed-by-ID workflow_dir semantics
Assisted-By: 🤖 Claude Code
* docs: document context.workflow_dir and SPECKIT_WORKFLOW_DIR
Add reference documentation for the new workflow_dir runtime value in
both workflows/README.md and docs/reference/workflows.md so workflow
authors can discover the feature and its semantics.
Assisted-By: 🤖 Claude Code
* fix: clarify installed workflow_dir is an absolute path (#3469)
The documentation for context.workflow_dir described the installed-by-ID
case as ".specify/workflows/<id>/" which appears relative, contradicting
the "resolved absolute path" semantics. Clarified that it is the absolute
path to the installation directory.
Assisted-By: 🤖 Claude Code
* fix: apply bot review suggestions (#3469)
Applied fixes from bot review comments:
- Comment #3580005128: Quote sys.executable in shell step env var test
- Comment #3580005174: Quote sys.executable in no-env-var test
Assisted-By: 🤖 Claude Code
* fix: apply bot review suggestions (#3469)
Applied fixes from bot review comments:
- Comment #3587146944: Quote interpolated workflow_dir path in example
Assisted-By: 🤖 Claude Code
_run_fan_out coerces max_concurrency with int() inside except (TypeError,
ValueError). int(float('inf')) raises OverflowError, which is not in that tuple,
so a YAML 'max_concurrency: .inf' crashed the whole run with an uncaught
OverflowError instead of the documented 'cannot be coerced -> sequential'
fallback. Add OverflowError to the except tuple (nan already coerced via
ValueError).
Extends the existing invalid-value parametrization with float('inf')/nan (fails
before on inf: OverflowError; passes after: sequential, all items in order).
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(presets): seed constitution from preset constitution-template (#3272)
The constitution is the only template materialized to a live file
(.specify/memory/constitution.md) rather than resolved on demand, yet
ensure_constitution_from_template hardcoded a copy from the core template
and ignored PresetResolver. Combined with init seeding the constitution
before preset installation, a preset's constitution-template (e.g.
strategy: replace with a ratified constitution) could never go live.
Changes:
- ensure_constitution_from_template now resolves constitution-template
through PresetResolver, so a preset/override/extension wins and core is
the fallback.
- init seeds the constitution after preset installation so init --preset
uses the resolved stack.
- install_from_directory re-seeds memory/constitution.md from the resolved
preset template, guarded to only act when the memory file is missing or
still contains generic placeholder tokens — authored constitutions are
never overwritten. Covers preset add and install_from_zip.
- Tests for preset seeding, placeholder re-seed, authored-constitution
preservation, override resolution, and resolver-aware init seeding.
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* fix(presets): compose constitution-template when seeding memory
Take on review feedback from Copilot and gglachant:
- constitution seeding previously copied the top layer file path verbatim
even when the winning layer used a composing strategy
(prepend/append/wrap), which could leave {CORE_TEMPLATE} unresolved.
- both seeding paths now inspect resolver layers and only copy verbatim for
replace; non-replace strategies materialize composed content via
PresetResolver.resolve_content().
- add regression tests for wrap strategy composition in both
PresetManager seeding and ensure_constitution_from_template.
- add a drift-guard test pinning _CONSTITUTION_PLACEHOLDER_TOKENS to the
placeholders in templates/constitution-template.md.
Assisted-by: GitHub Copilot (model: GPT-5.3-Codex, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* refactor(presets): unify constitution template materialization
Address latest Copilot feedback on the constitution seeding path:
- moved resolver/layer I/O behind the existing-memory fast path in init
- corrected tracker output for composed materialization
- deduplicated materialization logic shared by init and preset install seeding
into presets._materialize_constitution_template()
Behavior is unchanged for replace strategies (copy verbatim) and remains
composed for prepend/append/wrap via resolve_content().
Assisted-by: GitHub Copilot (model: GPT-5.3-Codex, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* fix(init): restore shutil import
The constitution materialization refactor removed the module import, but init
still uses shutil.rmtree when cleaning up a failed new-project initialization.
Restore the import so the required ruff check passes.
Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
* fix(presets): harden constitution materialization
Address the outstanding review batch for preset constitution seeding:
- use checked atomic writes and reject symlinked memory paths
- replace placeholder heuristics with hash/source provenance
- rematerialize unchanged generated constitutions by resolver priority
- preserve authored or edited constitutions, including placeholder mentions
- warn non-fatally when post-install materialization cannot complete
- retain exact core-template comparison for legacy projects without provenance
Add focused provenance, priority, symlink, and failure-path coverage, and
update integration inventories for the generated provenance sidecar.
Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1b2c095d-b45c-4d52-8d56-bd6121d96ab6
* fix(presets): reconcile constitution after removal
When the removed preset supplied constitution-template, rematerialize the
winning remaining resolver layer only if provenance proves the live file is
still generated and unchanged. Preserve edited constitutions and report
post-removal reconciliation failures as non-fatal warnings.
Add coverage for restoring the core layer, falling back from a removed
higher-priority preset, and preserving edited generated content.
Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1b2c095d-b45c-4d52-8d56-bd6121d96ab6
* fix(presets): tighten legacy constitution provenance
Trust only the immutable bundled/source constitution template when migrating
legacy projects without provenance. Do not infer core provenance from mutable
project templates or preset source labels, including IDs beginning with core.
Also detect convention-based constitution-template files before preset removal
so unchanged generated constitutions reconcile to the next resolver layer.
Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1b2c095d-b45c-4d52-8d56-bd6121d96ab6
* fix(presets): preserve files with invalid provenance
Use immutable-core legacy migration only when the provenance sidecar is absent.
If a sidecar is malformed or its hash does not match the live constitution,
treat the file as edited and preserve it.
Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1b2c095d-b45c-4d52-8d56-bd6121d96ab6
* fix(presets): reconcile constitution on stack changes
Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1b2c095d-b45c-4d52-8d56-bd6121d96ab6
* fix(presets): guard constitution reconciliation edges
Assisted-by: GitHub Copilot (model: GPT-5.6 Sol, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1b2c095d-b45c-4d52-8d56-bd6121d96ab6
---------
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>
`WhileStep.validate()` and `DoWhileStep.validate()` already reject a
non-list `steps` body, but the engine's `execute()` path does not
auto-validate (see `WorkflowEngine.load_workflow`, whose docstring notes
the definition is "not yet validated"). On an unvalidated run the body
is returned as `next_steps`, and the engine feeds it straight into
`_execute_steps`, which iterates it as step mappings. A non-list `steps`
— a single mapping or scalar authoring mistake — was iterated
element-wise (a dict yields its string keys, a str its characters) and
raised `AttributeError` on `.get()`, taking down the whole run; the
engine invokes `step_impl.execute()` with no surrounding try/except.
Guard both `execute` paths to return a FAILED StepResult naming the type
error instead, mirroring the if/switch non-list-branch and fan-out
non-list `items` handling. The do-while body always dispatches on the
first call, so its guard is unconditional; the while body only
dispatches when the condition is truthy, so its guard fires only then —
a false condition leaves a non-list `steps` benign and the step
completes, unchanged. The condition/expression is still evaluated first,
so its result is surfaced in the step output for downstream context.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(extensions): port git extension scripts to Python
Ports git-common, initialize-repo, auto-commit, and
create-new-feature-branch to extensions/git/scripts/python/,
mirroring the bash/PowerShell twins. Parity tests run each bash
script and its Python twin in identical projects and compare
output, exit codes, and resulting git state.
Fixes#3282
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix: match bash error message for whitespace-only descriptions
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Handle unreadable git-config.yml and assert stderr parity
An unreadable config file raised OSError with a full traceback from
_parse_auto_commit_config. Treat it like a missing config: auto-commit
stays disabled. Covered by a chmod-000 test (skipped on non-POSIX and
as root).
_assert_parity now also compares stderr so warning or usage-text
regressions between the bash and Python twins fail the suite. All
existing parity tests pass with the stricter assertion.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix(extensions/git): pass script path to core.get_repo_root for cwd-outside-repo callers
Without script_file, core.get_repo_root() falls back to Path.cwd() when
SPECIFY_INIT_DIR is unset and no .specify root is found upward — the
bash twin instead falls back to the script's install location
(.specify/scripts/...). Pass script_file so both twins resolve the
same repo_root; TypeError fallback keeps older cores working.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* test: exercise SPECIFY_INIT_DIR from outside the project
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix(extensions/git): handle UnicodeDecodeError and USER/USERNAME fallback
- Catch (OSError, UnicodeDecodeError) when reading git-config.yml in
create_new_feature_branch.py, initialize_repo.py, and auto_commit.py
so invalid UTF-8 config falls back to defaults instead of crashing
with a traceback.
- Fall back to USERNAME (then "unknown") when USER is unset when
deriving the branch author token, matching the PowerShell twin's
Windows-friendly fallback chain.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix(extensions/git): platform-aware persist hint and stronger SPECIFY_INIT_DIR test
- Add a shared _persist_hint() helper in create_new_feature_branch.py
and use it for both the JSON-mode stderr hint and the human-readable
stdout hint, so there is a single place emitting the SPECIFY_FEATURE
persistence guidance. On Windows (os.name == "nt") it prints
PowerShell $env:VAR = "..." syntax; elsewhere it keeps the existing
POSIX export VAR=... syntax (parity with the bash twin).
- Rework test_specify_init_dir_resolves_target_project so SPECIFY_INIT_DIR
is the only thing that can produce the observed result: the script now
runs from a separate host_proj (no existing specs, so script/cwd-based
discovery would yield 001) while SPECIFY_INIT_DIR points at a different
target_proj that already has an existing spec (007-existing, so the
override must yield 008). The old version pointed SPECIFY_INIT_DIR at
the same project the script was installed in, so it passed even if the
env var were ignored.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix(extensions): tolerate missing Git executable
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix(extensions): quote PowerShell persist hint
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix(git): match bash persist hint escaping
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix(git): ignore unterminated config record
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* test(git): handle Windows persist hint parity
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix(init): install Python shared scripts
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* test(git): normalize Windows persistence hints
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* chore: bump version to 0.12.15
* chore: begin 0.12.16.dev0 development
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
* fix(workflows): raise catalog error, not raw ValueError, on a malformed catalog URL
The four catalog URL validators in `workflows/catalog.py`
(`WorkflowCatalog`/`StepCatalog` `_validate_catalog_url`, and the nested
fetch-path validators) accessed `urlparse(url).hostname` unguarded. A
malformed authority — e.g. an unterminated IPv6 bracket `https://[::1`
or a bracketed non-IP host `https://[not-an-ip]` — makes urlparse /
hostname raise `ValueError`.
Each validator's contract is to raise a domain error
(`WorkflowValidationError` / `StepValidationError` /
`WorkflowCatalogError` / `StepCatalogError`), and the command handlers
catch only those. So `specify workflow catalog add "https://[::1"`
surfaced an uncaught `ValueError` traceback instead of the clean
`Error: Catalog URL is malformed` + exit 1 that a bad URL should give.
The fetch-path validators also run on the post-redirect `resp.geturl()`,
so a hostile redirect target could crash the fetch the same way.
Guard each `urlparse`/`.hostname` access with `try/except ValueError ->
domain error`, mirroring the fixes already applied to
`specify_cli.catalogs` (#3435) and the bundler adapters (#3433). Also
read `hostname` once and reuse it for the host check, matching those
siblings.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* test(workflows): cover post-redirect malformed-URL guard (#3484 review)
Copilot review asked for regression tests on the fetch-path validators that
re-check resp.geturl() after redirects — the branch that turns a malformed
redirect target into a domain error instead of a raw ValueError.
- test_fetch_malformed_redirect_target_raises_catalog_error on both
TestWorkflowCatalog and TestStepCatalog: stub open_url with a response whose
geturl() is malformed (https://[::1 / https://[not-an-ip]/x) while entry.url
is valid, so validation only trips on the redirect target, and assert
_fetch_single_catalog raises WorkflowCatalogError / StepCatalogError with a
"malformed" message (force_refresh + fresh project_dir so no cache masks it).
- Test-the-test: both fail on pre-fix source (raw ValueError re-wrapped as
"...Invalid IPv6 URL", no "malformed" match) and pass with the guard.
Also merges latest upstream/main into the branch.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(workflows): evaluate 'in'/'not in' safely on a non-iterable right operand (#3447)
The `in` / `not in` operators in `_evaluate_simple_expression` only guarded
`right is not None`, but `left in right` also raises `TypeError` for any other
non-iterable right operand (int, bool, float). So a workflow condition like
`{{ inputs.tag in inputs.count }}` where `count` is a number leaked a raw
`TypeError: argument of type 'int' is not iterable` and crashed the whole run,
instead of evaluating like the None case beside it.
This was asymmetric with `_safe_compare`, which already swallows `TypeError`
and returns False for the ordering operators.
Add a `_safe_contains` helper (mirroring `_safe_compare`) that treats both a
None and a non-container right operand as "nothing is contained": `in` -> False,
`not in` -> True. Add a regression test covering int/bool/float/None right
operands and asserting genuine containment against iterables still works.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* fix(workflows): address review feedback on #3468#3447 was fixed independently by #3448 (merged first), which added the
same _safe_membership helper this branch introduced. Per Copilot review:
- Revert the redundant _safe_contains rename in expressions.py so the file
matches main; the working membership guard already lives there.
- Drop the duplicate test_in_operator_non_iterable_right_operand test and
fold its only new coverage (not in against float/bool/None right operands,
which the base test only checked for the int case) into the existing
test_membership_against_non_iterable_is_false_not_error.
Also merges latest upstream/main into the branch.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
