diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml
new file mode 100644
index 0000000000..535974e9b3
--- /dev/null
+++ b/.github/workflows/publish-pypi.yml
@@ -0,0 +1,79 @@
+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:
+ contents: read
+ actions: write
+ steps:
+ - name: Verify tag format
+ 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: Checkout release tag
+ uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+ with:
+ ref: refs/tags/${{ inputs.tag }}
+
+ - name: Install uv
+ uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+
+ - name: Set up Python
+ uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+ with:
+ python-version: "3.13"
+
+ - name: Verify tag matches package version
+ run: |
+ TAG_VERSION="${{ inputs.tag }}"
+ TAG_VERSION="${TAG_VERSION#v}"
+ PROJECT_VERSION="$(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
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index b35bc30ec2..6932d95e6b 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -65,11 +65,21 @@ jobs:
cat > release_notes.md << NOTES_EOF
## Install
+ From [PyPI](https://pypi.org/project/specify-cli/):
+
\`\`\`bash
- uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@${VERSION}
+ uv tool install 'specify-cli==${VERSION_NO_V}'
specify init my-project
\`\`\`
+ Or install from source:
+
+ \`\`\`bash
+ uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@${VERSION}
+ \`\`\`
+
+ > **Note:** The PyPI package is published after this GitHub release. If the version is not yet available on PyPI, use the source install above.
+
NOTES_EOF
echo "## What's Changed" >> release_notes.md
diff --git a/README.md b/README.md
index 0a0b4119b2..44ec94bf84 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
-
+
🌱 Spec Kit
Build high-quality software faster.