diff --git a/scripts/epic-execute-lib/INIT.md b/scripts/epic-execute-lib/INIT.md
new file mode 100644
index 000000000..74ca32b4a
--- /dev/null
+++ b/scripts/epic-execute-lib/INIT.md
@@ -0,0 +1,306 @@
+# Epic Execute - Dependencies & Setup
+
+This document describes the required and optional dependencies for running the `epic-execute.sh` script and its library modules.
+
+## Required Dependencies
+
+### Core Requirements
+
+| Package | Purpose | Installation |
+|---------|---------|--------------|
+| `bash` | Shell interpreter (v4.0+) | Pre-installed on macOS/Linux |
+| `git` | Version control operations | Pre-installed or `brew install git` |
+| `claude` | Claude Code CLI for AI-powered execution | `npm install -g @anthropic-ai/claude-code` |
+
+### Required CLI Tools
+
+| Tool | Purpose | macOS | Linux (Debian/Ubuntu) |
+|------|---------|-------|----------------------|
+| `timeout` | Command timeout handling | `brew install coreutils` (use `gtimeout`) | Pre-installed |
+| `sed` | Text processing | Pre-installed (BSD) | Pre-installed (GNU) |
+| `grep` | Pattern matching | Pre-installed | Pre-installed |
+| `awk` | Text processing | Pre-installed | Pre-installed |
+| `date` | Timestamp generation | Pre-installed | Pre-installed |
+| `wc` | Character/line counting | Pre-installed | Pre-installed |
+
+## Recommended Dependencies
+
+These tools enhance functionality but have fallback behavior if missing:
+
+### yq (YAML Processing)
+
+**Strongly Recommended** - Used for YAML file manipulation (metrics, story status updates).
+
+```bash
+# macOS (Homebrew)
+brew install yq
+
+# Linux (Go version - recommended)
+go install github.com/mikefarah/yq/v4@latest
+
+# Linux (snap)
+snap install yq
+
+# Linux (wget binary)
+wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq
+chmod +x /usr/local/bin/yq
+```
+
+**Important:** The script expects the [mikefarah/yq](https://github.com/mikefarah/yq) Go version (v4+), NOT the Python `yq` (kislyuk/yq). The Python version has different syntax and will trigger fallback mode.
+
+Without `yq`:
+- YAML updates use `sed` fallback (less reliable)
+- Metrics updates may be deferred
+- Story status updates may fail silently
+
+### jq (JSON Processing)
+
+**Recommended** - Used for JSON output parsing from Claude responses.
+
+```bash
+# macOS
+brew install jq
+
+# Linux (Debian/Ubuntu)
+apt-get install jq
+
+# Linux (RHEL/CentOS)
+yum install jq
+```
+
+Without `jq`:
+- JSON parsing falls back to regex patterns (less accurate)
+- Some structured output extraction may fail
+
+### xmllint (XML Validation)
+
+**Optional** - Used for validating XML workflow files.
+
+```bash
+# macOS
+# Pre-installed as part of libxml2
+
+# Linux (Debian/Ubuntu)
+apt-get install libxml2-utils
+
+# Linux (RHEL/CentOS)
+yum install libxml2
+```
+
+Without `xmllint`:
+- XML validation uses basic pattern matching
+- Invalid XML may not be detected until runtime
+
+## Project-Specific Test Runners
+
+The regression gate module auto-detects project type and requires the appropriate test runner:
+
+| Project Type | Detection File | Required Tool |
+|--------------|----------------|---------------|
+| Node.js/TypeScript | `package.json` | `npm` (with `test` script) |
+| Rust | `Cargo.toml` | `cargo` |
+| Go | `go.mod` | `go` |
+| Python | `requirements.txt` or `pyproject.toml` | `pytest` |
+
+## Quick Setup Script
+
+Run this to check and install all dependencies on macOS:
+
+```bash
+#!/bin/bash
+# epic-execute-setup.sh
+
+echo "Checking epic-execute dependencies..."
+
+# Check required tools
+for tool in git bash; do
+    if command -v $tool >/dev/null 2>&1; then
+        echo "✓ $tool installed"
+    else
+        echo "✗ $tool NOT FOUND - please install"
+    fi
+done
+
+# Check Claude CLI
+if command -v claude >/dev/null 2>&1; then
+    echo "✓ claude CLI installed"
+else
+    echo "✗ claude CLI NOT FOUND"
+    echo "  Install with: npm install -g @anthropic-ai/claude-code"
+fi
+
+# Check yq (Go version)
+if command -v yq >/dev/null 2>&1; then
+    if yq --version 2>&1 | grep -qE "(mikefarah|version.*v4)"; then
+        echo "✓ yq (Go version) installed"
+    else
+        echo "⚠ yq installed but may be Python version - recommend Go version"
+        echo "  Install with: brew install yq"
+    fi
+else
+    echo "⚠ yq NOT FOUND - YAML updates will use sed fallback"
+    echo "  Install with: brew install yq"
+fi
+
+# Check jq
+if command -v jq >/dev/null 2>&1; then
+    echo "✓ jq installed"
+else
+    echo "⚠ jq NOT FOUND - JSON parsing will use regex fallback"
+    echo "  Install with: brew install jq"
+fi
+
+# Check xmllint
+if command -v xmllint >/dev/null 2>&1; then
+    echo "✓ xmllint installed"
+else
+    echo "⚠ xmllint NOT FOUND - XML validation will be limited"
+fi
+
+# Check timeout (coreutils on macOS)
+if command -v timeout >/dev/null 2>&1 || command -v gtimeout >/dev/null 2>&1; then
+    echo "✓ timeout command available"
+else
+    echo "⚠ timeout NOT FOUND"
+    echo "  Install with: brew install coreutils"
+fi
+
+echo ""
+echo "Dependency check complete."
+```
+
+## Environment Variables
+
+The script respects these environment variables:
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `CLAUDE_TIMEOUT` | `600` | Timeout in seconds for Claude invocations |
+| `MAX_PROMPT_SIZE` | `150000` | Maximum prompt size in bytes |
+| `RETRY_MAX_ATTEMPTS` | `3` | Max retry attempts for transient failures |
+| `RETRY_INITIAL_DELAY` | `5` | Initial retry delay in seconds |
+| `RETRY_MAX_DELAY` | `60` | Maximum retry delay in seconds |
+| `PROTECTED_BRANCHES` | `main master` | Branches that block direct commits |
+| `VERBOSE` | `false` | Enable verbose logging |
+
+## Directory Structure & Path Configuration
+
+The `epic-execute.sh` script expects specific directory structures in your project. Before running, inspect your repository and ensure paths are configured correctly.
+
+### BMAD-METHOD Repository Structure
+
+The script sources BMAD workflows from these locations relative to the script:
+
+```
+BMAD-METHOD/
+├── scripts/
+│   ├── epic-execute.sh              # Main script
+│   └── epic-execute-lib/            # Library modules
+│       ├── utils.sh
+│       ├── json-output.sh
+│       ├── decision-log.sh
+│       ├── design-phase.sh
+│       ├── tdd-flow.sh
+│       └── regression-gate.sh
+└── src/
+    ├── core/
+    │   └── tasks/
+    │       └── workflow.xml         # Core workflow executor
+    └── modules/
+        └── bmm/
+            └── workflows/
+                └── 4-implementation/
+                    ├── dev-story/           # Dev phase workflow
+                    │   ├── workflow.yaml
+                    │   ├── instructions.xml
+                    │   └── checklist.md
+                    ├── code-review/         # Review phase workflow
+                    │   ├── workflow.yaml
+                    │   ├── instructions.xml
+                    │   └── checklist.md
+                    └── epic-execute/        # Quality gate steps
+                        ├── steps/
+                        │   ├── step-02b-arch-compliance.md
+                        │   ├── step-03b-test-quality.md
+                        │   ├── step-03c-traceability.md
+                        │   └── step-04-generate-uat.md
+                        └── templates/
+                            └── uat-template.md
+```
+
+### Target Project Structure
+
+The script expects your **target project** (where stories are implemented) to have:
+
+```
+your-project/
+├── docs/
+│   ├── stories/           # Story markdown files (e.g., 1-1-feature.md)
+│   ├── epics/             # Epic definition files
+│   ├── sprints/           # Sprint planning files
+│   ├── sprint-artifacts/  # Generated metrics, checkpoints, decision logs
+│   │   ├── metrics/
+│   │   ├── traceability/
+│   │   └── test-specs/
+│   └── uat/               # Generated UAT documents
+└── bmad/                  # Optional: local BMAD configuration
+```
+
+### Path Resolution
+
+The script determines paths as follows:
+
+```bash
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"    # Two levels up from script
+BMAD_SRC_DIR="$SCRIPT_DIR/.."                       # One level up (scripts parent)
+```
+
+**Important:** If you install BMAD-METHOD differently (e.g., as a submodule, npm package, or symlink), you may need to adjust `PROJECT_ROOT` detection in `epic-execute.sh` lines 104-106.
+
+### Inspecting Your Setup
+
+Before first run, verify your paths:
+
+```bash
+# From your target project root, check BMAD-METHOD location
+ls -la ./node_modules/bmad-method/scripts/ 2>/dev/null || \
+ls -la ./bmad-method/scripts/ 2>/dev/null || \
+echo "BMAD-METHOD not found - check installation"
+
+# Verify workflow files exist
+BMAD_PATH="<path-to-bmad-method>"
+ls -la "$BMAD_PATH/src/modules/bmm/workflows/4-implementation/dev-story/"
+ls -la "$BMAD_PATH/src/modules/bmm/workflows/4-implementation/code-review/"
+ls -la "$BMAD_PATH/src/core/tasks/workflow.xml"
+
+# Verify your project has required directories
+ls -la ./docs/stories/
+ls -la ./docs/epics/
+```
+
+### Creating Missing Directories
+
+If your project doesn't have the expected structure:
+
+```bash
+# Create required directories
+mkdir -p docs/{stories,epics,sprints,sprint-artifacts,uat}
+mkdir -p docs/sprint-artifacts/{metrics,traceability,test-specs}
+```
+
+## Verification
+
+After installing dependencies, verify the setup:
+
+```bash
+# Run the script with --dry-run to verify setup
+./scripts/epic-execute.sh <epic-id> --dry-run --verbose
+```
+
+The verbose output will show:
+- Platform detection
+- yq availability and version
+- Protected branch configuration
+- Workflow file validation results
+- Missing workflow files (if any)