docs(scripts): document the 'py' script type and sh/ps migration plan (#3284)

[mnriem]

Part of #3277. Closes #3284.

Completes the docs sub-issue for the workflow-script unification effort: brings the remaining user-visible docs in line with the Python (py) script variant and records the retention/deprecation plan for the shell variants.

Changes

• AGENTS.md
  • New "Script References (scripts: frontmatter)" subsection documenting the sh/ps/py block and where each variant lives.
  • Clarified the {SCRIPT} placeholder resolution (resolved from scripts: per the project's --script sh|ps|py selection).
  • New "Script Types and Migration" section: why py is recommended (no extra runtime, single source of truth, parity-tested), current defaults/availability, and a phased sh/ps deprecation path.
  • Noted the Python update_agent_context.py 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/.

Migration/deprecation stance

sh/ps are retained for now — nothing is removed. py is documented as recommended but remains opt-in; the OS-based default is unchanged. Removal is gated on adoption (not just parity) via the phased plan in AGENTS.md.

Acceptance (per #3284)

• AGENTS.md updated (Argument Patterns, Command File Formats, script-type references)
• README/devcontainer notes updated as needed
• Migration path / when sh/ps get deprecated is defined
• Documentation reflects the py option and the migration path

---

Opened by GitHub Copilot (model: Claude Opus 4.8) on behalf of @mnriem. Changes were generated autonomously; see the Assisted-by: trailer on the commit.

[Copilot]

Pull request overview

Documents Python workflow scripts and the planned shell-script migration.

Changes:

• Documents py script selection, locations, and migration phases.
• Updates quickstart, local-development, and integration references.
• Auto-approves Python scripts in the devcontainer.

Show a summary per file

File	Description
AGENTS.md	Adds Python script and migration guidance.
docs/quickstart.md	Mentions Python script selection.
docs/local-development.md	Documents local Python script usage.
docs/reference/integrations.md	Adds py to integration options.
.devcontainer/devcontainer.json	Auto-approves Python script paths.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 5/5 changed files
• Comments generated: 5
• Review effort level: Medium

[mnriem]

Addressed all five review comments in 66c4c67:

• Fixed the agent-context Python path to its real extensions/agent-context/scripts/python/update_agent_context.py location (was written as a non-existent top-level scripts/).
• Qualified the scripts: frontmatter statement so it only claims coverage for templates that actually invoke a helper script (constitution/specify have none).
• Narrowed the availability claim: py covers the core command templates; the bundled extensions ship Python scripts on disk but their command templates still hard-code the Bash/PowerShell invocations, so --script py does not yet route extension commands to Python.
• Reworded quickstart, local-development, and the AGENTS.md defaults bullet to describe the interactive prompt vs. the non-interactive OS default instead of "auto-selects".
• Added --script py to the "wrong script type" troubleshooting row in local-development.

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8); changes generated autonomously.

[Copilot]

Review details

Comments suppressed due to low confidence (3)

AGENTS.md:273

• This is broader than the implementation: the bundled agent-context and git command templates invoke helper scripts but do not use scripts: frontmatter (as the new caveat at line 365 acknowledges). Scope this rule to core command templates so the contributor guidance does not require a format those extension templates currently violate.

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

AGENTS.md:355

• The claim that every command template carries all three variants contradicts the documented extension limitation below: the agent-context and git command templates call helpers but still hard-code only Bash/PowerShell. Narrow this statement to the core templates.

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

AGENTS.md:361

• “Every Python script has output-parity tests against its shell counterparts” overstates the coverage. For example, git_common.py is covered by direct unit tests rather than output parity, and tests/extensions/git/test_git_extension_python_parity.py:1-5 compares the executable ports with Bash, not both Bash and PowerShell. Describe parity coverage without claiming every file is directly compared to every counterpart.

- **Parity-tested.** Every Python script has output-parity tests against its shell counterparts, so the stdout contract agents rely on is identical.

• Files reviewed: 5/5 changed files
• Comments generated: 2
• Review effort level: Medium

[mnriem]

Addressed the second review round in 1a37275.

The bigger change: I removed the four-phase deprecation timeline from AGENTS.md. On reflection (and prompted by the missing-adoption-signal comment), a speculative removal schedule is roadmap content rather than contributor guidance, and it read as aspiration since no phase defined an actionable trigger. AGENTS.md now keeps the concrete contributor rule — all three script variants are first-class and must be updated together with tests kept green — plus a one-line current-posture note that making py the default and retiring sh/ps is future work gated on adoption, tracked under the #3277 epic.

Accuracy fixes:

• No longer claims dual-maintenance is already eliminated; "single source of truth" is reframed as the intended direction, with an explicit note that all three variants are still maintained in parallel today.
• Parity coverage is described accurately: Python ports have output-parity tests where the contract is stdout-based and unit tests elsewhere (verified test_git_extension_python_parity.py compares Bash vs Python only), rather than claiming every file is compared to every counterpart.
• Scoped the scripts: frontmatter rule to core command templates and noted the agent-context/git extension templates don't use it yet.

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8); changes generated autonomously.

[Copilot]

Review details

Comments suppressed due to low confidence (1)

AGENTS.md:371

• The promised migration/deprecation plan is still missing here. This only says retirement is “future work gated on adoption”; it does not define the phased path claimed in the PR description, what adoption evidence/threshold permits changing the default, or the conditions and notice period for deprecating/removing sh and ps. Please document those stages and gates (or revise the PR’s acceptance claim) so issue #3284’s requirement to define when/whether deprecation happens is actually met.

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.

• Files reviewed: 5/5 changed files
• Comments generated: 0 new
• Review effort level: Medium