diff --git a/README.md b/README.md
index 9103d4d..123d55a 100644
--- a/README.md
+++ b/README.md
@@ -4,11 +4,25 @@ A portable, file-based issue tracking and development workflow for teams.
 
 ## Quick Start
 
-1. **Clone this repo** into your new project
-2. **Install dependencies**: `pnpm install` (or npm, yarn)
-3. **Run setup**: `pnpm run setup` (installs pre-commit hook)
-4. **Read the docs**: See `docs/workflow/INDEX.md`
-5. **Start working**: See `docs/workflow/WORKFLOW.md`
+```bash
+# Clone this repo into your new project
+git clone https://git.fbrns.co/shoko/workflow.git my-new-project
+cd my-new-project
+
+# Remove git history (optional, for a fresh start)
+rm -rf .git
+
+# Initialize git
+git init
+
+# Setup (installs pnpm if missing, dependencies, and pre-commit hook)
+pnpm run setup
+
+# Remove this README (it's the template's README)
+rm README.md
+```
+
+**That's it.** The setup script handles everything.
 
 ## What This Is
 
@@ -18,6 +32,14 @@ A portable, file-based issue tracking and development workflow for teams.
 - **Humans approve reasoning**, not code line-by-line
 - **Pre-commit hooks enforce** issue format before any commit
 
+## Requirements
+
+- **Node.js** (recommended: https://nodejs.org)
+  - If you don't have Node.js, the setup script will install `pnpm` using `corepack` or `npm`
+- **Git**
+
+No other dependencies required for the workflow itself.
+
 ## File Structure
 
 ```
@@ -32,30 +54,44 @@ A portable, file-based issue tracking and development workflow for teams.
 │   └── example/          # Example issues
 ├── .hooks/               # Pre-commit validators
 │   └── issue-linter.js   # Issue format validator
-└── package.json         # Setup scripts
+├── scripts/
+│   └── setup.sh          # Setup script
+└── package.json         # Setup commands
 ```
 
-## Setup
+## Setup Command
 
 ```bash
-# Clone this repo into your new project
-git clone https://git.fbrns.co/shoko/workflow.git my-new-project
-cd my-new-project
+pnpm run setup
+```
 
-# Remove git history (optional, for a fresh start)
-rm -rf .git
+This will:
+1. Check for `pnpm`, install it if missing (via corepack or npm)
+2. Install dependencies
+3. Install the pre-commit hook in `.git/hooks/`
 
-# Initialize git
-git init
+If Node.js isn't installed, the script will tell you to install it first.
 
-# Install dependencies
+## Manual Setup (Without pnpm)
+
+If you prefer not to use pnpm:
+
+```bash
+# 1. Install Node.js from https://nodejs.org
+
+# 2. Install pnpm
+npm install -g pnpm
+
+# 3. Install dependencies
 pnpm install
 
-# Setup pre-commit hook
-pnpm run setup
-
-# Remove this README (it's the template's README)
-rm README.md
+# 4. Manually install pre-commit hook
+mkdir -p .git/hooks
+cat > .git/hooks/pre-commit << 'EOF'
+#!/bin/bash
+node .hooks/issue-linter.js
+EOF
+chmod +x .git/hooks/pre-commit
 ```
 
 ## For Teams
@@ -73,6 +109,44 @@ To update the template for all projects:
 - [Step-by-Step Workflow](docs/workflow/WORKFLOW.md)
 - [Agent Prompts](docs/workflow/AGENT-PROMPTS.md)
 
+## Troubleshooting
+
+### "pnpm not found" during setup
+
+The setup script tries to install pnpm automatically. If it fails:
+
+```bash
+# Install Node.js first
+# Then enable pnpm via corepack
+corepack enable
+corepack prepare pnpm@latest --activate
+
+# Or install via npm
+npm install -g pnpm
+
+# Re-run setup
+pnpm run setup
+```
+
+### Pre-commit hook not running
+
+```bash
+# Make sure the hook is executable
+chmod +x .git/hooks/pre-commit
+
+# Test the hook manually
+node .hooks/issue-linter.js
+```
+
+### "git commit rejected" errors
+
+The pre-commit hook is rejecting your commit because:
+- Code changed without a corresponding issue file
+- Issue file is missing required fields
+- Issue has `done` status but is incomplete
+
+Fix the issue file and try again. Run `node .hooks/issue-linter.js` for details.
+
 ## License
 
 Internal use. See https://git.fbrns.co/shoko/workflow
diff --git a/package.json b/package.json
index 5f2b9d9..9603f69 100644
--- a/package.json
+++ b/package.json
@@ -4,11 +4,8 @@
   "description": "Standard issue-based workflow template for teams",
   "private": true,
   "scripts": {
-    "setup": "node .hooks/issue-linter.js --setup",
+    "setup": "bash scripts/setup.sh",
     "validate:issues": "node .hooks/issue-linter.js",
     "test": "echo \"Add your test commands here\""
-  },
-  "devDependencies": {
-    "pre-commit-hook": "^3.0.0"
   }
 }
diff --git a/scripts/setup.sh b/scripts/setup.sh
new file mode 100644
index 0000000..a4c5056
--- /dev/null
+++ b/scripts/setup.sh
@@ -0,0 +1,104 @@
+#!/bin/bash
+#
+# Setup script for workflow template
+# - Installs pnpm if missing
+# - Installs dependencies
+# - Sets up pre-commit hook
+#
+
+set -e
+
+echo "=========================================="
+echo "Workflow Template Setup"
+echo "=========================================="
+echo ""
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Step 1: Check/install pnpm
+echo "Checking for pnpm..."
+
+if command -v pnpm &> /dev/null; then
+    echo -e "${GREEN}pnpm found: $(pnpm --version)${NC}"
+else
+    echo -e "${YELLOW}pnpm not found. Installing...${NC}"
+    
+    # Try corepack first (ships with Node 16+)
+    if command -v corepack &> /dev/null; then
+        echo "Using corepack to enable pnpm..."
+        corepack enable
+        corepack prepare pnpm@latest --activate
+    # Try npm as fallback
+    elif command -v npm &> /dev/null; then
+        echo "Using npm to install pnpm globally..."
+        npm install -g pnpm
+    else
+        echo ""
+        echo -e "${RED}ERROR: Neither pnpm, corepack, nor npm found.${NC}"
+        echo ""
+        echo "Please install Node.js first:"
+        echo "  - https://nodejs.org (recommended)"
+        echo "  - Or via your system's package manager"
+        echo ""
+        echo "After installing Node.js, re-run this setup:"
+        echo "  pnpm run setup"
+        echo ""
+        exit 1
+    fi
+    
+    echo -e "${GREEN}pnpm installed: $(pnpm --version)${NC}"
+fi
+
+echo ""
+
+# Step 2: Install dependencies
+echo "Installing dependencies..."
+pnpm install
+
+# Step 3: Install pre-commit hook
+echo ""
+echo "Setting up pre-commit hook..."
+
+# Detect git directory
+if [ -d ".git" ]; then
+    mkdir -p .git/hooks
+else
+    echo -e "${YELLOW}Warning: .git directory not found. Run 'git init' first if this is a new repo.${NC}"
+    echo "Creating hooks directory anyway..."
+    mkdir -p .git/hooks
+fi
+
+# Create pre-commit hook
+cat > .git/hooks/pre-commit << 'EOF'
+#!/bin/bash
+# Pre-commit hook for issue-based workflow
+# Automatically installed by pnpm run setup
+
+node .hooks/issue-linter.js
+EOF
+
+chmod +x .git/hooks/pre-commit
+
+# Also make setup script executable
+chmod +x scripts/setup.sh
+
+echo -e "${GREEN}Pre-commit hook installed.${NC}"
+echo ""
+
+# Step 4: Summary
+echo "=========================================="
+echo -e "${GREEN}Setup complete!${NC}"
+echo "=========================================="
+echo ""
+echo "Next steps:"
+echo "  1. Read docs/workflow/INDEX.md"
+echo "  2. Check .issues/INDEX.md for open issues"
+echo "  3. Start working on an issue or create a new one"
+echo ""
+echo "The pre-commit hook will validate issue files before every commit."
+echo "Code changes without a valid issue file will be rejected."
+echo ""