Skip to content

Commit 66c4c67

Browse files
mnriemCopilot
andcommitted
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 <[email protected]> Copilot-Session: 298d6ec2-a330-49bc-9394-fe2b77f25ff3
1 parent 272aeea commit 66c4c67

3 files changed

Lines changed: 7 additions & 7 deletions

File tree

‎AGENTS.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -187,7 +187,7 @@ context_markers:
187187
end: "<!-- SPECKIT END -->"
188188
```
189189
190-
- The Specify CLI does **not** write this config. When `context_file` is empty, the extension's bundled scripts self-seed it by looking up the active integration's key in the extension's own `agent-context-defaults.json` map (`extensions/agent-context/scripts/bash/update-agent-context.sh`, `.ps1`, and `scripts/python/update_agent_context.py`). The CLI registry is never consulted — all agent→context-file knowledge lives inside the extension.
190+
- The Specify CLI does **not** write this config. When `context_file` is empty, the extension's bundled scripts self-seed it by looking up the active integration's key in the extension's own `agent-context-defaults.json` map (`extensions/agent-context/scripts/bash/update-agent-context.sh`, `.ps1`, and `extensions/agent-context/scripts/python/update_agent_context.py`). The CLI registry is never consulted — all agent→context-file knowledge lives inside the extension.
191191
- `context_markers.{start,end}` are read solely by the extension's scripts; they default to the Spec Kit markers shown above and can be customized by editing `agent-context-config.yml` directly.
192192

193193
Existing projects created by older Spec Kit versions keep working: any previously written managed section or extension config is left intact and is only ever updated by the extension when run.
@@ -352,7 +352,7 @@ 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`. Each command template carries all three in its `scripts:` frontmatter (see [Script References](#script-references-scripts-frontmatter)).
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).
356356

357357
### Why Python is recommended
358358

@@ -362,8 +362,8 @@ Spec Kit ships every workflow script in three interchangeable variants — POSIX
362362

363363
### Defaults and availability
364364

365-
- `py` is available today for all commands and both bundled extensions (`agent-context`, `git`).
366-
- The interactive/auto default is still OS-based: `sh` on Linux/macOS, `ps` on Windows. `py` is opt-in via `--script py`.
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+
- 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`.
367367
- `sh` and `ps` remain fully supported. Nothing is removed.
368368

369369
### Deprecation path

‎docs/local-development.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
This guide shows how to iterate on the `specify` CLI locally without publishing a release or committing to `main` first.
44

5-
> Scripts are available as Bash (`.sh`), PowerShell (`.ps1`), and Python (`.py`) variants. The CLI auto-selects a shell variant based on OS unless you pass `--script sh|ps|py`.
5+
> Scripts are available as Bash (`.sh`), PowerShell (`.ps1`), and Python (`.py`) variants. Interactive `specify init` prompts you to choose one; non-interactive runs default to a shell variant for your OS. Pass `--script sh|ps|py` to select explicitly.
66
77
## 1. Clone and Switch Branches
88

@@ -189,7 +189,7 @@ rm -rf .venv dist build *.egg-info
189189
| `ModuleNotFoundError: typer` | Run `uv pip install -e .` |
190190
| Scripts not executable (Linux) | Re-run init or `chmod +x scripts/*.sh` |
191191
| Git commands unavailable | Install the git extension with `specify extension add git` |
192-
| Wrong script type downloaded | Pass `--script sh` or `--script ps` explicitly |
192+
| Wrong script type downloaded | Pass `--script sh`, `--script ps`, or `--script py` explicitly |
193193
| TLS errors on corporate network | Configure your environment's certificate store or proxy. The `--skip-tls` flag is deprecated and has no effect. |
194194

195195
## 14. Next Steps

‎docs/quickstart.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
This guide will help you get started with Spec-Driven Development using Spec Kit. Throughout, we illustrate each step with a running example: **Taskify**, a small team productivity platform.
44

55
> [!NOTE]
6-
> Automation scripts are provided as Bash (`.sh`), PowerShell (`.ps1`), and Python (`.py`) variants. The `specify` CLI auto-selects a shell variant based on your OS unless you pass `--script sh|ps|py`.
6+
> Automation scripts are provided as Bash (`.sh`), PowerShell (`.ps1`), and Python (`.py`) variants. Interactive `specify init` prompts you to choose one; non-interactive runs default to a shell variant for your OS. Pass `--script sh|ps|py` to select explicitly.
77
88
> [!NOTE]
99
> Commands are shown here in `/speckit.*` form, but the exact invocation depends on your agent. Some skills-based agents use `$speckit-*` (e.g. Codex, ZCode) or `/skill:speckit-*` (e.g. Kimi). Use whichever form your agent exposes — the steps are otherwise identical.

0 commit comments

Comments
 (0)