Skip to content

Commit 1a37275

Browse files
mnriemCopilot
andcommitted
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
1 parent 66c4c67 commit 1a37275

1 file changed

Lines changed: 8 additions & 15 deletions

File tree

‎AGENTS.md‎

Lines changed: 8 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -270,7 +270,7 @@ echo "✅ Done"
270270

271271
### Script References (`scripts:` frontmatter)
272272

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`):
274274

275275
```yaml
276276
scripts:
@@ -285,7 +285,7 @@ scripts:
285285
| `ps` | PowerShell | `scripts/powershell/*.ps1` |
286286
| `py` | Python | `scripts/python/*.py` |
287287

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. 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).)
289289

290290
### Markdown Format
291291

@@ -352,30 +352,23 @@ Different agents use different argument placeholders. The placeholder used in co
352352

353353
## Script Types and Migration
354354

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).
356356

357357
### Why Python is recommended
358358

359359
- **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.
362362

363363
### Defaults and availability
364364

365365
- `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.
366366
- 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.
368368

369-
### Deprecation path
369+
### Parity rule for contributors
370370

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.
375-
3. **Then** — `sh`/`ps` receive a soft-deprecation notice (still installed, marked legacy).
376-
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.
379372

380373
## Special Processing Requirements
381374

0 commit comments

Comments
 (0)