You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 1a37275
Browse filesBrowse the repository at this point in the historyBrowse files
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 <[email protected]>
Copilot-Session: 298d6ec2-a330-49bc-9394-fe2b77f25ff3
Copy file name to clipboardExpand all lines: AGENTS.md
+8-15Lines changed: 8 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -270,7 +270,7 @@ echo "✅ Done"
270
270
271
271
### Script References (`scripts:` frontmatter)
272
272
273
-
Command templates that invoke a helper script declare it in a `scripts:` frontmatter block with one line per supported script type. The `{SCRIPT}` placeholder in the command body is replaced at install time with the entry matching the project's selected script type (`--script sh|ps|py`):
273
+
Core command templates (`templates/commands/*.md`) that invoke a helper script declare it in a `scripts:` frontmatter block with one line per supported script type. The `{SCRIPT}` placeholder in the command body is replaced at install time with the entry matching the project's selected script type (`--script sh|ps|py`):
All three entries must be present and behaviorally equivalent — agents parse the same stdout contract (`FEATURE_DIR:…`, `AVAILABLE_DOCS:…`, `--json` shapes) regardless of which one runs. See [Script Types and Migration](#script-types-and-migration).
288
+
All three entries must be present and behaviorally equivalent — agents parse the same stdout contract (`FEATURE_DIR:…`, `AVAILABLE_DOCS:…`, `--json` shapes) regardless of which one runs. (The bundled `agent-context` and `git` extension command templates also invoke helpers but do not yet use `scripts:` frontmatter — see [Script Types and Migration](#script-types-and-migration).)
289
289
290
290
### Markdown Format
291
291
@@ -352,30 +352,23 @@ Different agents use different argument placeholders. The placeholder used in co
352
352
353
353
## Script Types and Migration
354
354
355
-
Spec Kit ships every workflow script in three interchangeable variants — POSIX shell (`sh`), PowerShell (`ps`), and Python (`py`) — selected per project with `specify init --script sh|ps|py`. Every command template that invokes a helper script carries all three in its `scripts:` frontmatter (templates that don't call a script, e.g. `constitution`/`specify`, have no `scripts:` block); see [Script References](#script-references-scripts-frontmatter).
355
+
Spec Kit ships every core workflow script in three interchangeable variants — POSIX shell (`sh`), PowerShell (`ps`), and Python (`py`) — selected per project with `specify init --script sh|ps|py`. Each core command template that invokes a helper script carries all three in its `scripts:` frontmatter (templates that don't call a script, e.g. `constitution`/`specify`, have no `scripts:` block); see [Script References](#script-references-scripts-frontmatter).
356
356
357
357
### Why Python is recommended
358
358
359
359
- **No extra runtime.** The `specify` CLI is already Python, so the interpreter is guaranteed present — `py` adds no new dependency.
360
-
- **Single source of truth.** The shell variants require paired `.sh` + `.ps1` maintenance and diverge on JSON handling (`jq` vs manual parsing). The Python port removes that dual-maintenance and the `jq` dependency.
361
-
- **Parity-tested.** Every Python script has output-parity tests against its shell counterparts, so the stdout contract agents rely on is identical.
360
+
- **Path toward a single source of truth.** The shell variants require paired `.sh` + `.ps1` maintenance and diverge on JSON handling (`jq` vs manual parsing). The Python variant avoids `jq` and is intended to eventually replace that dual-maintenance — but that consolidation has not happened yet: all three variants are still maintained in parallel (see the parity rule below).
361
+
- **Parity-tested.** The Python ports are covered by tests — output-parity tests against the shell scripts where the contract is stdout-based, and direct unit tests elsewhere — so the stdout contract agents rely on stays stable.
362
362
363
363
### Defaults and availability
364
364
365
365
- `py`is available today for the core command templates (via their `scripts:` frontmatter). The bundled extensions (`agent-context`, `git`) ship Python script variants on disk, but their command templates still hard-code the Bash/PowerShell invocations, so `--script py` does not yet route those extension commands to Python — wiring `py` into the extension command templates is tracked separately.
366
366
- Selection is per project: interactive `specify init` prompts for the script type, while non-interactive runs default to a shell variant by OS (`sh` on Linux/macOS, `ps` on Windows). `py` is chosen at the prompt or via `--script py`.
367
-
- `sh`and `ps` remain fully supported. Nothing is removed.
367
+
- `sh`and `ps` remain fully supported. Nothing is removed, and `py` is not yet the default.
368
368
369
-
### Deprecation path
369
+
### Parity rule for contributors
370
370
371
-
`sh`/`ps` are **retained for now**. Removal is gated on adoption, not just parity, and proceeds in phases:
372
-
373
-
1. **Now** — all three variants ship; `py` documented as recommended; OS default unchanged.
374
-
2. **Next** — `py` becomes the default once it has shipped for several releases with no parity regressions.
4. **Eventually** — `sh`/`ps` are removed in a future major release.
377
-
378
-
Until step 4, treat all three script types as first-class: any change to a workflow script must update `sh`, `ps`, and `py` together and keep their parity tests green.
371
+
All three script types are first-class: any change to a workflow script must update `sh`, `ps`, and `py` together and keep their tests (parity and unit) green. Making `py` the default and eventually retiring `sh`/`ps` is future work gated on adoption, tracked under the script-unification epic ([#3277](https://github.com/github/spec-kit/issues/3277)) — not something to act on from this doc.
0 commit comments