ros/spec-kit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor with platform-specific constraints

Browse Source
This commit is contained in:
Den Delimarsky 🌺
2025-09-12 10:27:43 -07:00
parent 57024454bf
commit 5787bb5537
28 changed files with 730 additions and 758 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/installation.md
View File

@@ -2,7 +2,7 @@
## Prerequisites
- **Linux/macOS** (or WSL2 on Windows)
- **Linux/macOS** (or Windows; PowerShell scripts now supported without WSL)
- AI coding agent: [Claude Code](https://www.anthropic.com/claude-code), [GitHub Copilot](https://code.visualstudio.com/), or [Gemini CLI](https://github.com/google-gemini/gemini-cli)
- [uv](https://docs.astral.sh/uv/) for package management
- [Python 3.11+](https://www.python.org/downloads/)
@@ -34,6 +34,21 @@ uvx --from git+https://github.com/github/spec-kit.git specify init <project_name
uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --ai copilot
```
### Specify Script Type (Shell vs PowerShell)
All automation scripts now have both Bash (`.sh`) and PowerShell (`.ps1`) variants.
Auto behavior:
- Windows default: `ps`
- Other OS default: `sh`
- Interactive mode: you'll be prompted unless you pass `--script`
Force a specific script type:
```bash
uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --script sh
uvx --from git+https://github.com/github/spec-kit.git specify init <project_name> --script ps
```
### Ignore Agent Tools Check
If you prefer to get the templates without checking for the right tools:
@@ -49,6 +64,8 @@ After initialization, you should see the following commands available in your AI
- `/plan` - Generate implementation plans
- `/tasks` - Break down into actionable tasks
The `.specify/scripts` directory will contain both `.sh` and `.ps1` scripts.
## Troubleshooting
### Git Credential Manager on Linux

25
docs/local-development.md
View File

@@ -2,6 +2,8 @@
This guide shows how to iterate on the `specify` CLI locally without publishing a release or committing to `main` first.
> Scripts now have both Bash (`.sh`) and PowerShell (`.ps1`) variants. The CLI auto-selects based on OS unless you pass `--script sh|ps`.
## 1. Clone and Switch Branches
```bash
@@ -18,13 +20,13 @@ You can execute the CLI via the module entrypoint without installing anything:
```bash
# From repo root
python -m src.specify_cli --help
python -m src.specify_cli init demo-project --ai claude --ignore-agent-tools
python -m src.specify_cli init demo-project --ai claude --ignore-agent-tools --script sh
```
If you prefer invoking the script file style (uses shebang):
```bash
python src/specify_cli/__init__.py init demo-project
python src/specify_cli/__init__.py init demo-project --script ps
```
## 3. Use Editable Install (Isolated Environment)
@@ -34,7 +36,7 @@ Create an isolated environment using `uv` so dependencies resolve exactly like e
```bash
# Create & activate virtual env (uv auto-manages .venv)
uv venv
source .venv/bin/activate # or on Windows: .venv\\Scripts\\activate
source .venv/bin/activate # or on Windows PowerShell: .venv\Scripts\Activate.ps1
# Install project in editable mode
uv pip install -e .
@@ -50,7 +52,7 @@ Re-running after code edits requires no reinstall because of editable mode.
`uvx` can run from a local path (or a Git ref) to simulate user flows:
```bash
uvx --from . specify init demo-uvx --ai copilot --ignore-agent-tools
uvx --from . specify init demo-uvx --ai copilot --ignore-agent-tools --script sh
```
You can also point uvx at a specific branch without merging:
@@ -58,7 +60,7 @@ You can also point uvx at a specific branch without merging:
```bash
# Push your working branch first
git push origin your-feature-branch
uvx --from git+https://github.com/github/spec-kit.git@your-feature-branch specify init demo-branch-test
uvx --from git+https://github.com/github/spec-kit.git@your-feature-branch specify init demo-branch-test --script ps
```
### 4a. Absolute Path uvx (Run From Anywhere)
@@ -67,13 +69,13 @@ If you're in another directory, use an absolute path instead of `.`:
```bash
uvx --from /mnt/c/GitHub/spec-kit specify --help
uvx --from /mnt/c/GitHub/spec-kit specify init demo-anywhere --ai copilot --ignore-agent-tools
uvx --from /mnt/c/GitHub/spec-kit specify init demo-anywhere --ai copilot --ignore-agent-tools --script sh
```
Set an environment variable for convenience:
```bash
export SPEC_KIT_SRC=/mnt/c/GitHub/spec-kit
uvx --from "$SPEC_KIT_SRC" specify init demo-env --ai copilot --ignore-agent-tools
uvx --from "$SPEC_KIT_SRC" specify init demo-env --ai copilot --ignore-agent-tools --script ps
```
(Optional) Define a shell function:
@@ -91,7 +93,7 @@ After running an `init`, check that shell scripts are executable on POSIX system
ls -l scripts | grep .sh
# Expect owner execute bit (e.g. -rwxr-xr-x)
```
On Windows this step is a no-op.
On Windows you will instead use the `.ps1` scripts (no chmod needed).
## 6. Run Lint / Basic Checks (Add Your Own)
@@ -116,7 +118,7 @@ When testing `init --here` in a dirty directory, create a temp workspace:
```bash
mkdir /tmp/spec-test && cd /tmp/spec-test
python -m src.specify_cli init --here --ai claude --ignore-agent-tools # if repo copied here
python -m src.specify_cli init --here --ai claude --ignore-agent-tools --script sh # if repo copied here
```
Or copy only the modified CLI portion if you want a lighter sandbox.
@@ -126,7 +128,7 @@ If you need to bypass TLS validation while experimenting:
```bash
specify check --skip-tls
specify init demo --skip-tls --ai gemini --ignore-agent-tools
specify init demo --skip-tls --ai gemini --ignore-agent-tools --script ps
```
(Use only for local experimentation.)
@@ -153,8 +155,9 @@ rm -rf .venv dist build *.egg-info
| Symptom | Fix |
|---------|-----|
| `ModuleNotFoundError: typer` | Run `uv pip install -e .` |
| Scripts not executable (Linux) | Re-run init (logic adds bits) or `chmod +x scripts/*.sh` |
| Scripts not executable (Linux) | Re-run init or `chmod +x scripts/*.sh` |
| Git step skipped | You passed `--no-git` or Git not installed |
| Wrong script type downloaded | Pass `--script sh` or `--script ps` explicitly |
| TLS errors on corporate network | Try `--skip-tls` (not for production) |
## 13. Next Steps

8
docs/quickstart.md
View File

@@ -2,6 +2,8 @@
This guide will help you get started with Spec-Driven Development using Spec Kit.
> NEW: All automation scripts now provide both Bash (`.sh`) and PowerShell (`.ps1`) variants. The `specify` CLI auto-selects based on OS unless you pass `--script sh|ps`.
## The 4-Step Process
### 1. Install Specify
@@ -12,6 +14,12 @@ Initialize your project depending on the coding agent you're using:
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
```
Pick script type explicitly (optional):
```bash
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME> --script ps # Force PowerShell
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME> --script sh # Force POSIX shell
```
### 2. Create the Spec
Use the `/specify` command to describe what you want to build. Focus on the **what** and **why**, not the tech stack.