Setup & Prerequisites

Prerequisites

Install the required tools before running any ADW:

# Claude Code CLI
npm install -g @anthropic-ai/claude-code

# uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# GitHub CLI
brew install gh          # macOS
# sudo apt install gh    # Linux
# winget install --id GitHub.cli  # Windows

# Authenticate GitHub
gh auth login
# GitHub.com → HTTPS → Yes (authenticate git) → Login with browser

# Verify all tools
claude --version
uv --version
gh auth status

Environment Setup

Copy the env template:

cp .env.sample .env

Fill in .env:

# REQUIRED
ANTHROPIC_API_KEY=sk-ant-...

# REQUIRED — GitHub Personal Access Token
# Create at: github.com → Settings → Developer settings → Personal access tokens → Fine-grained
# Permissions needed: Issues (r/w), Pull requests (r/w), Contents (r/w), Metadata (r)
GITHUB_PAT=ghp_...

# Optional — only if 'claude' is not in your PATH
CLAUDE_CODE_PATH=claude

# Optional — for uploading review screenshots directly into GitHub PR comments
CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_R2_ACCESS_KEY_ID=
CLOUDFLARE_R2_SECRET_ACCESS_KEY=
CLOUDFLARE_R2_BUCKET_NAME=
CLOUDFLARE_R2_PUBLIC_DOMAIN=

# Optional — Cloudflare tunnel token to expose webhook to the internet
CLOUDFLARED_TUNNEL_TOKEN=

GitHub Repository Setup

The ADW system reads issues, comments on them, creates branches, and opens PRs via the GitHub API. It needs a real repo with Issues enabled.

Point to your repo

# Remove any existing remote pointing to the source
git remote remove origin

# Create a new GitHub repo and push
gh repo create my-project --private --source=. --push

# Or manually
git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO.git
git push -u origin main

The system auto-detects your repo URL from the git remote. You can also pin it explicitly in .env:

GITHUB_REPO_URL=https://github.com/YOUR_USERNAME/YOUR_REPO

Fine-grained token permissions

Permission	Level
Issues	Read and write
Pull requests	Read and write
Contents	Read and write
Metadata	Read (required)

Verify GitHub setup

gh auth status
gh issue list    # Should return issues from your repo (empty is fine)

Health Check

Run this before your first ADW to catch configuration problems early:

uv run adws/adw_tests/health_check.py

Or from inside a Claude Code session:

/health_check

Fix everything it flags before proceeding.

Adding to an Existing Project

# Clone the code-factory-primer into a temp directory
git clone https://github.com/VilovietaSEO/code-factory-primer.git .cf-tmp

# Copy only the scaffolding files
cp -r .cf-tmp/.claude .cf-tmp/adws .cf-tmp/specs .cf-tmp/scripts .cf-tmp/.env.sample .

# Clean up
rm -rf .cf-tmp

Adapting to Your Project

1. scripts/start.sh and scripts/stop_apps.sh — replace with your project's start/stop commands
2. scripts/reset_db.sh — replace with your database reset if applicable
3. CLAUDE.md — create one describing your specific project (the /code-factory skill generates this automatically)
4. .claude/commands/feature.md — update the Relevant Files section to match your project structure

Everything else is drop-in portable.