diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 17baec857..7ecd05012 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,12 +38,7 @@ Here are a few things you can do that will increase the likelihood of your pull ## Development workflow -When working on spec-kit: - -1. Test changes with the `specify` CLI commands (`/specify`, `/plan`, `/tasks`) in your coding agent of choice -2. Verify templates are working correctly in `templates/` directory -3. Test script functionality in the `scripts/` directory -4. Ensure memory files (`memory/constitution.md`) are updated if major process changes are made +See `docs/local-development.md` for up-to-date, end-to-end instructions. ## AI contributions in Spec Kit diff --git a/README.md b/README.md index d5b371b73..58a383c33 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,7 @@ - [🎯 Experimental goals](#-experimental-goals) - [🔧 Prerequisites](#-prerequisites) - [📖 Learn more](#-learn-more) +- [🛠️ Local Development](docs/local-development.md) - [📋 Detailed process](#-detailed-process) - [🔍 Troubleshooting](#-troubleshooting) - [👥 Maintainers](#-maintainers) @@ -242,6 +243,7 @@ If you encounter issues with an agent, please open an issue so we can refine the - **[Complete Spec-Driven Development Methodology](./spec-driven.md)** - Deep dive into the full process - **[Detailed Walkthrough](#-detailed-process)** - Step-by-step implementation guide +- **[Local Development Guide](docs/local-development.md)** - Run the CLI from source, editable installs, uvx flows, and using locally built template ZIPs --- diff --git a/docs/local-development.md b/docs/local-development.md index 58f174bef..257f22316 100644 --- a/docs/local-development.md +++ b/docs/local-development.md @@ -4,6 +4,12 @@ This guide shows how to iterate on the `specify` CLI locally without publishing > Scripts now have both Bash (`.sh`) and PowerShell (`.ps1`) variants. The CLI auto-selects based on OS unless you pass `--script sh|ps`. +## Development Workflow (Checklist) +- Test the `specify` CLI flows (`/specify`, `/plan`, `/tasks`) for your changes +- Verify templates in `templates/` render and behave as expected +- Test scripts in `scripts/` for both `sh` and `ps` variants where applicable +- Update `memory/constitution.md` if you changed core process expectations + ## 1. Clone and Switch Branches ```bash @@ -85,6 +91,44 @@ specify-dev() { uvx --from /mnt/c/GitHub/spec-kit specify "$@"; } specify-dev --help ``` +### 4b. Use Locally Built Templates (No Network) + +Build the per-agent, per-script template archives locally and point the CLI at one ZIP via `SPECIFY_TEMPLATE_ZIP`. + +- Build on Linux + +```bash +chmod +x .github/workflows/scripts/create-release-packages.sh && \ +.github/workflows/scripts/create-release-packages.sh v0.0.1; \ +chmod -x .github/workflows/scripts/create-release-packages.sh +``` + +- Build on macOS (use Docker for GNU tools like `cp --parents`) + +```bash +docker run --rm -it -v "$PWD":/w -w /w ubuntu:24.04 bash -lc "apt-get update && apt-get install -y zip && chmod +x .github/workflows/scripts/create-release-packages.sh && .github/workflows/scripts/create-release-packages.sh v0.0.1 && chmod -x .github/workflows/scripts/create-release-packages.sh" +``` + +- (Optional) Build only specific variants + +```bash +AGENTS=claude,cursor SCRIPTS=sh .github/workflows/scripts/create-release-packages.sh v0.0.1 +``` + +- Run the CLI against a local ZIP (no network) + +```bash +SPECIFY_TEMPLATE_ZIP=/abs/path/spec-kit-template-claude-sh-v0.0.1.zip \ +uvx --refresh --no-cache --from /abs/path/to/spec-kit \ + specify init --here --ai claude --script sh --ignore-agent-tools +``` + +Notes: +- Keep `--ai` and `--script` consistent with the ZIP variant you built. +- On Linux, ensure `zip` is installed. On macOS, prefer the Docker method above. +- Artifacts are git-ignored by default (`spec-kit-template-*-v*.zip`, `sdd-*-package-*`). +- This flow mirrors the release packaging; it’s ideal for verifying template layout and agent-specific directories (Claude, Cursor, Copilot, Qwen, Gemini, opencode, Windsurf). + ## 5. Testing Script Permission Logic After running an `init`, check that shell scripts are executable on POSIX systems: @@ -142,6 +186,7 @@ specify init demo --skip-tls --ai gemini --ignore-agent-tools --script ps | Local uvx run (abs path) | `uvx --from /mnt/c/GitHub/spec-kit specify ...` | | Git branch uvx | `uvx --from git+URL@branch specify ...` | | Build wheel | `uv build` | +| Use locally built template | `SPECIFY_TEMPLATE_ZIP=… uvx --from … specify init …` | ## 11. Cleaning Up @@ -166,3 +211,47 @@ rm -rf .venv dist build *.egg-info - Open a PR when satisfied - (Optional) Tag a release once changes land in `main` +## 14. Distributing and testing your fork + +You can point the CLI at a different GitHub repository (e.g., your fork) for template downloads without changing code. Set these environment variables before running `specify`: + +- `SPECIFY_REPO_OWNER` — GitHub user/org that owns the repo +- `SPECIFY_REPO_NAME` — Repository name + +The CLI queries `https://api.github.com/repos///releases/latest` and selects the first asset whose filename contains `spec-kit-template-{ai}-{script}` and ends with `.zip`. + +Recommended asset naming (matches release packaging scripts): +`spec-kit-template--