diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml
new file mode 100644
index 0000000000..6cedde6841
--- /dev/null
+++ b/.github/workflows/publish-pypi.yml
@@ -0,0 +1,73 @@
+name: Publish to PyPI
+
+on:
+ workflow_dispatch:
+ inputs:
+ tag:
+ description: 'Release tag to publish (e.g., v0.10.1)'
+ required: true
+ type: string
+
+permissions:
+ contents: read
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ permissions:
+ actions: write
+ steps:
+ - name: Checkout release tag
+ uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+ with:
+ ref: ${{ inputs.tag }}
+
+ - name: Verify tag is a release
+ run: |
+ TAG="${{ inputs.tag }}"
+ if [[ ! "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+ echo "Error: '$TAG' is not a valid release tag (expected vX.Y.Z)"
+ exit 1
+ fi
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+
+ - name: Verify tag matches package version
+ run: |
+ TAG_VERSION="${{ inputs.tag }}"
+ TAG_VERSION="${TAG_VERSION#v}"
+ PROJECT_VERSION="$(uv run python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])')"
+ if [[ "$TAG_VERSION" != "$PROJECT_VERSION" ]]; then
+ echo "Error: Tag version ($TAG_VERSION) does not match pyproject.toml version ($PROJECT_VERSION)"
+ exit 1
+ fi
+
+ - name: Build package
+ run: uv build
+
+ - name: Upload build artifacts
+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+ with:
+ name: dist
+ path: dist/
+
+ publish:
+ needs: build
+ runs-on: ubuntu-latest
+ environment: pypi
+ permissions:
+ id-token: write
+ actions: read
+ steps:
+ - name: Download build artifacts
+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+ with:
+ name: dist
+ path: dist/
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+
+ - name: Publish to PyPI
+ run: uv publish --trusted-publishing always
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index b35bc30ec2..a22c7c34b5 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -66,10 +66,24 @@ jobs:
## Install
\`\`\`bash
- uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@${VERSION}
+ uv tool install specify-cli@latest
specify init my-project
\`\`\`
+ Or pin to this exact release:
+
+ \`\`\`bash
+ uv tool install specify-cli==${VERSION_NO_V}
+ \`\`\`
+
+ Or install from source:
+
+ \`\`\`bash
+ uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@${VERSION}
+ \`\`\`
+
+ > **Note:** PyPI publishing runs shortly after this release is created. If the PyPI version is not yet available, use the source install command above.
+
NOTES_EOF
echo "## What's Changed" >> release_notes.md
diff --git a/README.md b/README.md
index 0a0b4119b2..4a4c8c63ac 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
-
+
🌱 Spec Kit
Build high-quality software faster.