From 1db65aa6aa70f043e5b4989172f404b04e1dbada Mon Sep 17 00:00:00 2001
From: Shayne Boyer <spboyer@live.com>
Date: Mon, 22 Sep 2025 11:08:25 -0400
Subject: [PATCH] feat: add uv tool install instructions to README

- Add persistent installation option using 'uv tool install'
- Keep existing 'uvx' one-time usage option
- Add benefits section explaining advantages of persistent installation
- Reorganize installation section with clear option headers

Fixes #476
---
 README.md | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 7572728..e098dec 100644
--- a/README.md
+++ b/README.md
@@ -39,12 +39,38 @@ Spec-Driven Development **flips the script** on traditional software development
 
 ### 1. Install Specify
 
-Initialize your project depending on the coding agent you're using:
+Choose your preferred installation method:
+
+#### Option 1: Persistent Installation (Recommended)
+
+Install once and use everywhere:
+
+```bash
+uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
+```
+
+Then use the tool directly:
+
+```bash
+specify init <PROJECT_NAME>
+specify check
+```
+
+#### Option 2: One-time Usage
+
+Run directly without installing:
 
 ```bash
 uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
 ```
 
+**Benefits of persistent installation:**
+
+- Tool stays installed and available in PATH
+- No need to create shell aliases
+- Better tool management with `uv tool list`, `uv tool upgrade`, `uv tool uninstall`
+- Cleaner shell configuration
+
 ### 2. Establish project principles
 
 Use the **`/constitution`** command to create your project's governing principles and development guidelines that will guide all subsequent development.