forge-workflow 0.0.4 → 0.0.6

package/docs/SETUP.md

@@ -1,631 +1,663 @@
-# Forge Setup Guide
-
-Complete setup instructions for all AI agents and optional toolchain.
-
----
-
-## Table of Contents
-
-- [Installation Options](#installation-options)
-- [Agent-Specific Setup](#agent-specific-setup)
-- [Prerequisites](#prerequisites)
-- [Toolchain Setup](#toolchain-setup)
-- [External Services](#external-services)
-- [Troubleshooting](#troubleshooting)
-
----
-
-## Installation Options
-
-### Option 1: Bun (Recommended)
-
-```bash
-# Step 1: Install the package
-bun add forge-workflow
-
-# Step 2: Interactive setup
-bunx forge setup
-```
-
-**Interactive prompts**:
-1. Which agents do you use?
-2. Install Beads? (y/n) - Git-backed issue tracking
-3. Configure external services? (optional)
-
-**What gets created**:
-- `AGENTS.md` - Universal instructions (always)
-- Agent-specific files based on your selection
-- `docs/` folder with workflow guides
-
-### Option 2: Specify Agents Directly
-
-```bash
-# Install for specific agents
-bunx forge setup --agents claude,cursor,codex
-
-# Install for all agents
-bunx forge setup --all
-```
-
-### Option 3: curl (One-Command Install)
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/harshanandak/forge/main/install.sh | bash
-```
-
-**Interactive prompts**:
-1. Which agents do you use?
-2. Install Beads? (y/n)
-
-### Option 4: bun
-
-```bash
-bun add forge-workflow
-bunx forge setup
-```
-
----
-
-## Agent-Specific Setup
-
-### Claude Code
-
-**Files created**:
-- `CLAUDE.md` → Linked to `AGENTS.md`
-- `.claude/commands/` → 7 slash commands
-- `.claude/rules/workflow.md` → Workflow rules
-- `.claude/skills/forge-workflow/` → Skill files
-
-**Usage**:
-```bash
-/status
-/plan feature-name
-/dev
-/validate
-# ... etc
-```
-
-**Skills available**:
-- `forge-workflow` - All 7 stages
-- `parallel-deep-research` - Deep analysis and web research (if PARALLEL_API_KEY configured)
-- `sonarcloud-analysis` - Code quality (if SONARCLOUD_TOKEN configured)
-
----
-
-### Cursor
-
-**Files created**:
-- `.cursorrules` → Linked to `AGENTS.md`
-- `.cursor/rules/forge-workflow.mdc` → MDC rules
-- `.cursor/skills/forge-workflow/` → Skill files
-
-**Usage**:
-Cursor reads `.cursorrules` and follows the 7-stage workflow.
-
-**Commands**:
-Use Composer or Chat to reference stages:
-```
-"I'm at the /dev stage - help me write tests first"
-```
-
----
-
-### GitHub Copilot
-
-**Files created**:
-- `.github/copilot-instructions.md` → Linked to `AGENTS.md`
-- `.github/prompts/` → Workflow prompts
-
-**Usage**:
-Copilot reads instructions from `.github/copilot-instructions.md`.
-
-**In Copilot Chat**:
-```
-@workspace I'm starting a new feature, help me with the /plan stage
-```
-
----
-
-### Codex CLI
-
-**Files created**:
-- `AGENTS.md` → Primary instructions
-
-**Usage**:
-Codex CLI reads `AGENTS.md` and follows the documented workflow.
-
-**Example**:
-```
-codex "Let's follow the Forge workflow. Start with /plan login-button."
-```
-
----
-
-### Kilo Code, OpenCode, Goose
-
-**Files created**:
-- Agent-specific config pointing to `AGENTS.md`
-- Skill files in agent's skill directory
-
-**Usage**:
-All agents read `AGENTS.md` and follow the documented workflow.
-
-**Example (any agent)**:
-```
-"Let's follow the Forge workflow. I want to add a login button.
-Start with the /plan stage."
-```
-
----
-
-## Prerequisites
-
-### Required
-
-#### Git
-
-```bash
-# Verify installation
-git --version
-
-# If not installed:
-# macOS: brew install git
-# Windows: winget install Git.Git
-# Linux: sudo apt install git
-```
-
-#### GitHub CLI
-
-**Required for** `/ship`, `/review`, `/premerge` commands.
-
-```bash
-# macOS
-brew install gh
-
-# Windows
-winget install GitHub.cli
-
-# Linux
-sudo apt install gh
-
-# Authenticate
-gh auth login
-```
-
-**Follow prompts**:
-1. Select "GitHub.com"
-2. Select "HTTPS"
-3. Select "Login with a web browser"
-4. Copy one-time code and paste in browser
-
-**Verify**:
-```bash
-gh auth status
-```
-
----
-
-### Recommended
-
-#### Beads - Issue Tracking
-
-**Recommended for**: Multi-session work, team collaboration
-
-```bash
-# Install globally
-bun install -g @beads/bd
-
-# Initialize in your project
-cd your-project
-bd init
-
-# Verify
-bd list
-```
-
-**What it does**:
-- Git-backed issue tracking
-- Survives context clearing
-- Dependency tracking
-- Team-shareable
-
-[Full Beads guide in TOOLCHAIN.md](TOOLCHAIN.md#beads---issue-tracking-across-sessions)
-
----
-
-## Toolchain Setup
-
-### Beads Configuration
-
-After `bd init`, customize `.beads/config.yaml`:
-
-```yaml
-# .beads/config.yaml
-project:
-  name: "your-project"
-  prefix: "PROJ"  # Issue IDs: PROJ-1, PROJ-2, etc.
-
-priorities:
-  0: "critical"
-  1: "high"
-  2: "medium"
-  3: "low"
-  4: "backlog"
-
-statuses:
-  - "open"
-  - "in_progress"
-  - "blocked"
-  - "done"
-
-labels:
-  - "bug"
-  - "feature"
-  - "chore"
-  - "security"
-```
-
-**Custom prefix**:
-```bash
-bd init --prefix MYPROJ
-```
-
-**Stealth mode** (local only, don't commit):
-```bash
-bd init --stealth
-```
-
----
-
-## External Services
-
-Forge integrates with external services for enhanced capabilities. **All are optional** - Forge works standalone.
-
-### Code Review Tools
-
-| Tool | Pricing | Best For | Setup Time |
-|------|---------|----------|------------|
-| **GitHub Code Quality** | FREE | All repos | 0 min (built-in) |
-| **CodeRabbit** | FREE (OSS) | Open source | 2 min |
-| **Greptile** | $99+/mo | Enterprise | 5 min |
-
-**Recommendation**: Start with GitHub Code Quality (FREE, no setup).
-
-#### GitHub Code Quality Setup
-
-**Already enabled!** Zero configuration required.
-
-GitHub provides built-in code quality features:
-- Code scanning
-- Dependabot alerts
-- Secret scanning
-- Pull request checks
-
-#### CodeRabbit Setup (FREE for Open Source)
-
-```bash
-# 1. Visit https://coderabbit.ai
-# 2. Click "Sign in with GitHub"
-# 3. Install GitHub App
-# 4. Select repositories
-
-# Done! CodeRabbit reviews all PRs automatically.
-```
-
-#### Greptile Setup (Paid - Enterprise)
-
-```bash
-# 1. Get API key from https://app.greptile.com
-# 2. Add to .env.local
-GREPTILE_API_KEY=your-key
-CODE_REVIEW_TOOL=greptile
-
-# 3. Index repository (one-time)
-curl -X POST "https://api.greptile.com/v2/repositories" \
-  -H "Authorization: Bearer $GREPTILE_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "remote": "github",
-    "repository": "owner/repo",
-    "branch": "main"
-  }'
-```
-
----
-
-### Code Quality Tools
-
-| Tool | Pricing | Best For | Setup Time |
-|------|---------|----------|------------|
-| **ESLint** | FREE | All projects | 0 min (built-in) |
-| **SonarCloud** | 50k LoC FREE | Cloud hosting | 10 min |
-| **SonarQube** | FREE | Self-hosted | 15 min |
-
-**Recommendation**: Start with ESLint (FREE, already in your project).
-
-#### ESLint Setup
-
-**Already configured!** Just run:
-
-```bash
-bun run lint
-# or: npm run lint
-```
-
-#### SonarCloud Setup
-
-```bash
-# 1. Create account at https://sonarcloud.io
-# 2. Create new project, select your repo
-# 3. Get token from Account → Security
-# 4. Add to .env.local
-SONAR_TOKEN=your-token
-SONAR_ORGANIZATION=your-org
-SONAR_PROJECT_KEY=your-project
-CODE_QUALITY_TOOL=sonarcloud
-
-# 5. Create sonar-project.properties
-cat > sonar-project.properties << EOF
-sonar.organization=$SONAR_ORGANIZATION
-sonar.projectKey=$SONAR_PROJECT_KEY
-sonar.sources=src
-sonar.tests=tests
-sonar.test.inclusions=**/*.test.js,**/*.spec.js
-sonar.javascript.lcov.reportPaths=coverage/lcov.info
-EOF
-
-# 6. Run analysis locally
-bunx sonarqube-scanner
-
-# 7. Add to CI (.github/workflows/quality.yml)
-```
-
-**GitHub Actions**:
-```yaml
-# .github/workflows/quality.yml
-name: Code Quality
-on: [push, pull_request]
-
-jobs:
-  sonarcloud:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-        with:
-          fetch-depth: 0
-      - uses: sonarsource/sonarcloud-github-action@master
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
-```
-
-#### SonarQube Setup (Self-Hosted)
-
-```bash
-# 1. Start SonarQube with Docker
-docker run -d \
-  --name sonarqube \
-  -p 9000:9000 \
-  sonarqube:community
-
-# 2. Access at http://localhost:9000
-# Default login: admin/admin
-# Change password when prompted
-
-# 3. Create project in SonarQube UI
-# 4. Generate token (Administration → Security → Users)
-# 5. Add to .env.local
-SONARQUBE_URL=http://localhost:9000
-SONARQUBE_TOKEN=your-token
-CODE_QUALITY_TOOL=sonarqube
-
-# 6. Create sonar-project.properties
-cat > sonar-project.properties << EOF
-sonar.host.url=http://localhost:9000
-sonar.login=$SONARQUBE_TOKEN
-sonar.projectKey=your-project
-sonar.sources=src
-sonar.tests=tests
-EOF
-
-# 7. Run analysis
-bunx sonarqube-scanner
-```
-
----
-
-### Research Tools
-
-#### Parallel AI (Optional - Paid)
-
-**Used in** `/plan` stage for deep web research.
-
-```bash
-# 1. Get API key from https://platform.parallel.ai
-# 2. Add to .env.local
-PARALLEL_API_KEY=your-key
-
-# 3. Test
-API_KEY=$(grep "^PARALLEL_API_KEY=" .env.local | cut -d= -f2)
-curl -s -X POST "https://api.parallel.ai/v1beta/search" \
-  -H "x-api-key: $API_KEY" \
-  -H "Content-Type: application/json" \
-  -H "parallel-beta: search-extract-2025-10-10" \
-  -d '{"objective": "test query"}'
-```
-
-**Pricing**: Pay-as-you-go
-**Alternative**: Manual web search (FREE)
-
----
-
-## Environment Variables
-
-### Configuration File
-
-Create `.env.local` in your project root:
-
-```bash
-# .env.local (add to .gitignore!)
-
-# ===== TOOL SELECTION =====
-CODE_REVIEW_TOOL=github-code-quality  # or: coderabbit, greptile, none
-CODE_QUALITY_TOOL=eslint              # or: sonarcloud, sonarqube, none
-
-# ===== REQUIRED: GitHub =====
-GITHUB_TOKEN=ghp_xxxxxxxxxxxx
-
-# ===== OPTIONAL: Research =====
-PARALLEL_API_KEY=your-parallel-ai-key
-
-# ===== OPTIONAL: Code Review (Greptile) =====
-GREPTILE_API_KEY=your-greptile-key
-
-# ===== OPTIONAL: Code Quality (SonarCloud) =====
-SONAR_TOKEN=your-sonarcloud-token
-SONAR_ORGANIZATION=your-org
-SONAR_PROJECT_KEY=your-project
-
-# ===== OPTIONAL: Code Quality (SonarQube) =====
-SONARQUBE_URL=http://localhost:9000
-SONARQUBE_TOKEN=your-token
-```
-
-### Loading Variables
-
-**Forge includes a helper**:
-
-```bash
-# Load all variables
-source .claude/scripts/load-env.sh
-
-# Or manually
-export $(grep -v '^#' .env.local | xargs)
-```
-
-**In Claude Code** (automatic):
-Variables are loaded when running commands.
-
-**Security**:
-```bash
-# Add to .gitignore
-echo ".env.local" >> .gitignore
-```
-
----
-
-## Directory Structure After Setup
-
-```
-your-project/
-├── AGENTS.md                    # Universal (always created)
-├── CLAUDE.md                    # If Claude selected
-├── .cursorrules                 # If Cursor selected
-│
-├── .claude/                     # Claude Code files
-│   ├── commands/                # 7 workflow commands
-│   ├── rules/workflow.md
-│   ├── skills/forge-workflow/
-│   └── scripts/load-env.sh
-│
-├── .cursor/                     # Cursor files
-│   ├── rules/forge-workflow.mdc
-│   └── skills/forge-workflow/
-│
-├── docs/
-│   ├── TOOLCHAIN.md             # Tool reference
-│   ├── SETUP.md                 # This file
-│   ├── EXAMPLES.md              # Real examples
-│   ├── planning/PROGRESS.md     # Progress tracking
-│   └── research/TEMPLATE.md     # Research template
-│
-├── .beads/                      # If Beads installed
-│   ├── issues.jsonl
-│   ├── config.yaml
-│   └── .gitignore
-│
-└── .env.local                   # Your configuration (add to .gitignore!)
-```
-
----
-
-## Troubleshooting
-
-### "Command not found: bunx forge"
-
-```bash
-# Ensure forge-workflow is installed
-bun pm ls | grep forge-workflow
-
-# If not, install
-bun add forge-workflow
-```
-
-### "Permission denied: gh"
-
-```bash
-# Authenticate GitHub CLI
-gh auth login
-
-# Or check status
-gh auth status
-```
-
-### "Beads: command not found"
-
-```bash
-# Install globally
-bun install -g @beads/bd
-
-# Verify
-bd --version
-```
-
-### "SonarQube connection refused"
-
-```bash
-# Check if SonarQube is running
-docker ps | grep sonarqube
-
-# If not, start it
-docker start sonarqube
-
-# Or run fresh
-docker run -d --name sonarqube -p 9000:9000 sonarqube:community
-```
-
-### "Greptile API rate limit"
-
-**Wait** for rate limit to reset (usually 1 minute).
-
-**Or upgrade** to higher tier at https://greptile.com/pricing
-
-### "Parallel AI API key invalid"
-
-```bash
-# Verify key in .env.local
-grep PARALLEL_API_KEY .env.local
-
-# Test key
-curl -s -X POST "https://api.parallel.ai/v1beta/search" \
-  -H "x-api-key: YOUR_KEY" \
-  -H "Content-Type: application/json" \
-  -H "parallel-beta: search-extract-2025-10-10" \
-  -d '{"objective": "test"}'
-```
-
----
-
-## Next Steps
-
-✅ Setup complete? Try your [first feature](../QUICKSTART.md)
-
-📖 Learn the workflow in [AGENTS.md](../AGENTS.md)
-
-🛠️ Explore toolchain in [TOOLCHAIN.md](TOOLCHAIN.md)
-
-🎯 See examples in [EXAMPLES.md](EXAMPLES.md)
-
----
-
-**Questions?** → [GitHub Discussions](https://github.com/harshanandak/forge/discussions)
+# Forge Setup Guide
+
+Complete setup instructions for all AI agents and optional toolchain.
+
+---
+
+## Table of Contents
+
+- [Installation Options](#installation-options)
+- [Agent-Specific Setup](#agent-specific-setup)
+- [Prerequisites](#prerequisites)
+- [Toolchain Setup](#toolchain-setup)
+- [External Services](#external-services)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Installation Options
+
+### Option 1: Bun (Recommended)
+
+```bash
+# Step 1: Install the package (as dev dependency)
+bun add -D forge-workflow
+
+# Step 2: Interactive setup
+bunx forge setup
+```
+
+**Interactive prompts**:
+1. Which agents do you use?
+2. Install Beads? (y/n) - Git-backed issue tracking
+3. Configure external services? (optional)
+
+**What gets created**:
+- `AGENTS.md` - Universal instructions (always)
+- Agent-specific files based on your selection
+- `docs/` folder with workflow guides
+
+### Option 2: Specify Agents Directly
+
+```bash
+# Install for specific agents
+bunx forge setup --agents claude,cursor,codex
+
+# Install for all agents
+bunx forge setup --all
+```
+
+### Option 3: curl (One-Command Install)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/harshanandak/forge/main/install.sh | bash
+```
+
+> **Note**: `install.sh` is a thin bootstrapper that installs forge-workflow and delegates to `bunx forge setup`. All setup logic lives in the npm package.
+
+**Interactive prompts**:
+1. Which agents do you use?
+2. Install Beads? (y/n)
+
+### Option 4: bun
+
+```bash
+bun add -D forge-workflow
+bunx forge setup
+```
+
+---
+
+## Agent-Specific Setup
+
+### Claude Code
+
+**Files created**:
+- `CLAUDE.md` → Linked to `AGENTS.md`
+- `.claude/commands/` → 7 slash commands
+- `.claude/rules/workflow.md` → Workflow rules
+- `.claude/skills/forge-workflow/` → Skill files
+
+**Usage**:
+```bash
+/status
+/plan feature-name
+/dev
+/validate
+# ... etc
+```
+
+**Skills available**:
+- `forge-workflow` - All 7 stages
+- `parallel-deep-research` - Deep analysis and web research (if PARALLEL_API_KEY configured)
+- `sonarcloud-analysis` - Code quality (if SONARCLOUD_TOKEN configured)
+
+---
+
+### Cursor
+
+**Files created**:
+- `.cursorrules` → Linked to `AGENTS.md`
+- `.cursor/rules/forge-workflow.mdc` → MDC rules
+- `.cursor/skills/forge-workflow/` → Skill files
+
+**Usage**:
+Cursor reads `.cursorrules` and follows the 7-stage workflow.
+
+**Commands**:
+Use Composer or Chat to reference stages:
+```
+"I'm at the /dev stage - help me write tests first"
+```
+
+---
+
+### GitHub Copilot
+
+**Files created**:
+- `.github/copilot-instructions.md` → Linked to `AGENTS.md`
+- `.github/prompts/` → Workflow prompts
+
+**Usage**:
+Copilot reads instructions from `.github/copilot-instructions.md`.
+
+**In Copilot Chat**:
+```
+@workspace I'm starting a new feature, help me with the /plan stage
+```
+
+---
+
+### Codex CLI
+
+**Files created**:
+- `AGENTS.md` → Primary instructions
+
+**Usage**:
+Codex CLI reads `AGENTS.md` and follows the documented workflow.
+
+**Example**:
+```
+codex "Let's follow the Forge workflow. Start with /plan login-button."
+```
+
+---
+
+### Kilo Code, OpenCode, Goose
+
+**Files created**:
+- Agent-specific config pointing to `AGENTS.md`
+- Skill files in agent's skill directory
+
+**Usage**:
+All agents read `AGENTS.md` and follow the documented workflow.
+
+**Example (any agent)**:
+```
+"Let's follow the Forge workflow. I want to add a login button.
+Start with the /plan stage."
+```
+
+---
+
+## Prerequisites
+
+### Required
+
+#### Git
+
+```bash
+# Verify installation
+git --version
+
+# If not installed:
+# macOS: brew install git
+# Windows: winget install Git.Git
+# Linux: sudo apt install git
+```
+
+#### GitHub CLI
+
+**Required for** `/ship`, `/review`, `/premerge` commands.
+
+```bash
+# macOS
+brew install gh
+
+# Windows
+winget install GitHub.cli
+
+# Linux
+sudo apt install gh
+
+# Authenticate
+gh auth login
+```
+
+**Follow prompts**:
+1. Select "GitHub.com"
+2. Select "HTTPS"
+3. Select "Login with a web browser"
+4. Copy one-time code and paste in browser
+
+**Verify**:
+```bash
+gh auth status
+```
+
+---
+
+### Recommended
+
+#### Beads - Issue Tracking
+
+**Recommended for**: Multi-session work, team collaboration
+
+```bash
+# Install globally
+bun install -g @beads/bd
+
+# Initialize in your project
+cd your-project
+bd init
+
+# Verify
+bd list
+```
+
+**What it does**:
+- Git-backed issue tracking
+- Survives context clearing
+- Dependency tracking
+- Team-shareable
+
+[Full Beads guide in TOOLCHAIN.md](TOOLCHAIN.md#beads---issue-tracking-across-sessions)
+
+---
+
+## Toolchain Setup
+
+### Beads Configuration
+
+After `bd init`, customize `.beads/config.yaml`:
+
+```yaml
+# .beads/config.yaml
+project:
+  name: "your-project"
+  prefix: "PROJ"  # Issue IDs: PROJ-1, PROJ-2, etc.
+
+priorities:
+  0: "critical"
+  1: "high"
+  2: "medium"
+  3: "low"
+  4: "backlog"
+
+statuses:
+  - "open"
+  - "in_progress"
+  - "blocked"
+  - "done"
+
+labels:
+  - "bug"
+  - "feature"
+  - "chore"
+  - "security"
+```
+
+**Custom prefix**:
+```bash
+bd init --prefix MYPROJ
+```
+
+**Stealth mode** (local only, don't commit):
+```bash
+bd init --stealth
+```
+
+### Beads GitHub Sync
+
+The `--sync` flag during setup scaffolds a GitHub Actions workflow that syncs Beads issues with GitHub Issues bidirectionally.
+
+```bash
+# Enable Beads sync during setup
+bunx forge setup --sync
+```
+
+**What gets scaffolded**:
+- `.github/workflows/beads-sync.yml` - GitHub Actions workflow for bidirectional sync
+- PAT (Personal Access Token) configuration via `gh secret set`
+
+**PAT requirements**:
+- A GitHub PAT with `repo` scope is required for the sync workflow
+- During setup, Forge prompts to create and store the token as `BEADS_SYNC_TOKEN`
+- The token is stored as a GitHub Actions secret (never committed to the repo)
+
+**Manual PAT setup** (if skipped during setup):
+```bash
+# Create a PAT at https://github.com/settings/tokens
+# Then store it as a repo secret:
+gh secret set BEADS_SYNC_TOKEN --body "ghp_your_token_here"
+```
+
+**How sync works**:
+- On push: Beads issues are synced to GitHub Issues
+- On issue change: GitHub Issues are synced back to Beads
+- Conflict resolution: last-write-wins with timestamps
+
+---
+
+## External Services
+
+Forge integrates with external services for enhanced capabilities. **All are optional** - Forge works standalone.
+
+### Code Review Tools
+
+| Tool | Pricing | Best For | Setup Time |
+|------|---------|----------|------------|
+| **GitHub Code Quality** | FREE | All repos | 0 min (built-in) |
+| **CodeRabbit** | FREE (OSS) | Open source | 2 min |
+| **Greptile** | $99+/mo | Enterprise | 5 min |
+
+**Recommendation**: Start with GitHub Code Quality (FREE, no setup).
+
+#### GitHub Code Quality Setup
+
+**Already enabled!** Zero configuration required.
+
+GitHub provides built-in code quality features:
+- Code scanning
+- Dependabot alerts
+- Secret scanning
+- Pull request checks
+
+#### CodeRabbit Setup (FREE for Open Source)
+
+```bash
+# 1. Visit https://coderabbit.ai
+# 2. Click "Sign in with GitHub"
+# 3. Install GitHub App
+# 4. Select repositories
+
+# Done! CodeRabbit reviews all PRs automatically.
+```
+
+#### Greptile Setup (Paid - Enterprise)
+
+```bash
+# 1. Get API key from https://app.greptile.com
+# 2. Add to .env.local
+GREPTILE_API_KEY=your-key
+CODE_REVIEW_TOOL=greptile
+
+# 3. Index repository (one-time)
+curl -X POST "https://api.greptile.com/v2/repositories" \
+  -H "Authorization: Bearer $GREPTILE_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "remote": "github",
+    "repository": "owner/repo",
+    "branch": "main"
+  }'
+```
+
+---
+
+### Code Quality Tools
+
+| Tool | Pricing | Best For | Setup Time |
+|------|---------|----------|------------|
+| **ESLint** | FREE | All projects | 0 min (built-in) |
+| **SonarCloud** | 50k LoC FREE | Cloud hosting | 10 min |
+| **SonarQube** | FREE | Self-hosted | 15 min |
+
+**Recommendation**: Start with ESLint (FREE, already in your project).
+
+#### ESLint Setup
+
+**Already configured!** Just run:
+
+```bash
+bun run lint
+# or: npm run lint
+```
+
+#### SonarCloud Setup
+
+```bash
+# 1. Create account at https://sonarcloud.io
+# 2. Create new project, select your repo
+# 3. Get token from Account → Security
+# 4. Add to .env.local
+SONAR_TOKEN=your-token
+SONAR_ORGANIZATION=your-org
+SONAR_PROJECT_KEY=your-project
+CODE_QUALITY_TOOL=sonarcloud
+
+# 5. Create sonar-project.properties
+cat > sonar-project.properties << EOF
+sonar.organization=$SONAR_ORGANIZATION
+sonar.projectKey=$SONAR_PROJECT_KEY
+sonar.sources=src
+sonar.tests=tests
+sonar.test.inclusions=**/*.test.js,**/*.spec.js
+sonar.javascript.lcov.reportPaths=coverage/lcov.info
+EOF
+
+# 6. Run analysis locally
+bunx sonarqube-scanner
+
+# 7. Add to CI (.github/workflows/quality.yml)
+```
+
+**GitHub Actions**:
+```yaml
+# .github/workflows/quality.yml
+name: Code Quality
+on: [push, pull_request]
+
+jobs:
+  sonarcloud:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - uses: sonarsource/sonarcloud-github-action@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+```
+
+#### SonarQube Setup (Self-Hosted)
+
+```bash
+# 1. Start SonarQube with Docker
+docker run -d \
+  --name sonarqube \
+  -p 9000:9000 \
+  sonarqube:community
+
+# 2. Access at http://localhost:9000
+# Default login: admin/admin
+# Change password when prompted
+
+# 3. Create project in SonarQube UI
+# 4. Generate token (Administration → Security → Users)
+# 5. Add to .env.local
+SONARQUBE_URL=http://localhost:9000
+SONARQUBE_TOKEN=your-token
+CODE_QUALITY_TOOL=sonarqube
+
+# 6. Create sonar-project.properties
+cat > sonar-project.properties << EOF
+sonar.host.url=http://localhost:9000
+sonar.login=$SONARQUBE_TOKEN
+sonar.projectKey=your-project
+sonar.sources=src
+sonar.tests=tests
+EOF
+
+# 7. Run analysis
+bunx sonarqube-scanner
+```
+
+---
+
+### Research Tools
+
+#### Parallel AI (Optional - Paid)
+
+**Used in** `/plan` stage for deep web research.
+
+```bash
+# 1. Get API key from https://platform.parallel.ai
+# 2. Add to .env.local
+PARALLEL_API_KEY=your-key
+
+# 3. Test
+API_KEY=$(grep "^PARALLEL_API_KEY=" .env.local | cut -d= -f2)
+curl -s -X POST "https://api.parallel.ai/v1beta/search" \
+  -H "x-api-key: $API_KEY" \
+  -H "Content-Type: application/json" \
+  -H "parallel-beta: search-extract-2025-10-10" \
+  -d '{"objective": "test query"}'
+```
+
+**Pricing**: Pay-as-you-go
+**Alternative**: Manual web search (FREE)
+
+---
+
+## Environment Variables
+
+### Configuration File
+
+Create `.env.local` in your project root:
+
+```bash
+# .env.local (add to .gitignore!)
+
+# ===== TOOL SELECTION =====
+CODE_REVIEW_TOOL=github-code-quality  # or: coderabbit, greptile, none
+CODE_QUALITY_TOOL=eslint              # or: sonarcloud, sonarqube, none
+
+# ===== REQUIRED: GitHub =====
+GITHUB_TOKEN=ghp_xxxxxxxxxxxx
+
+# ===== OPTIONAL: Research =====
+PARALLEL_API_KEY=your-parallel-ai-key
+
+# ===== OPTIONAL: Code Review (Greptile) =====
+GREPTILE_API_KEY=your-greptile-key
+
+# ===== OPTIONAL: Code Quality (SonarCloud) =====
+SONAR_TOKEN=your-sonarcloud-token
+SONAR_ORGANIZATION=your-org
+SONAR_PROJECT_KEY=your-project
+
+# ===== OPTIONAL: Code Quality (SonarQube) =====
+SONARQUBE_URL=http://localhost:9000
+SONARQUBE_TOKEN=your-token
+```
+
+### Loading Variables
+
+**Forge includes a helper**:
+
+```bash
+# Load all variables
+source .claude/scripts/load-env.sh
+
+# Or manually
+export $(grep -v '^#' .env.local | xargs)
+```
+
+**In Claude Code** (automatic):
+Variables are loaded when running commands.
+
+**Security**:
+```bash
+# Add to .gitignore
+echo ".env.local" >> .gitignore
+```
+
+---
+
+## Directory Structure After Setup
+
+```
+your-project/
+├── AGENTS.md                    # Universal (always created)
+├── CLAUDE.md                    # If Claude selected
+├── .cursorrules                 # If Cursor selected
+│
+├── .claude/                     # Claude Code files
+│   ├── commands/                # 7 workflow commands
+│   ├── rules/workflow.md
+│   ├── skills/forge-workflow/
+│   └── scripts/load-env.sh
+│
+├── .cursor/                     # Cursor files
+│   ├── rules/forge-workflow.mdc
+│   └── skills/forge-workflow/
+│
+├── docs/
+│   ├── TOOLCHAIN.md             # Tool reference
+│   ├── SETUP.md                 # This file
+│   ├── EXAMPLES.md              # Real examples
+│   ├── planning/PROGRESS.md     # Progress tracking
+│   └── research/TEMPLATE.md     # Research template
+│
+├── .beads/                      # If Beads installed
+│   ├── issues.jsonl
+│   ├── config.yaml
+│   └── .gitignore
+│
+└── .env.local                   # Your configuration (add to .gitignore!)
+```
+
+---
+
+## Troubleshooting
+
+### "Command not found: bunx forge"
+
+```bash
+# Ensure forge-workflow is installed
+bun pm ls | grep forge-workflow
+
+# If not, install
+bun add -D forge-workflow
+```
+
+### "Permission denied: gh"
+
+```bash
+# Authenticate GitHub CLI
+gh auth login
+
+# Or check status
+gh auth status
+```
+
+### "Beads: command not found"
+
+```bash
+# Install globally
+bun install -g @beads/bd
+
+# Verify
+bd --version
+```
+
+### "SonarQube connection refused"
+
+```bash
+# Check if SonarQube is running
+docker ps | grep sonarqube
+
+# If not, start it
+docker start sonarqube
+
+# Or run fresh
+docker run -d --name sonarqube -p 9000:9000 sonarqube:community
+```
+
+### "Greptile API rate limit"
+
+**Wait** for rate limit to reset (usually 1 minute).
+
+**Or upgrade** to higher tier at https://greptile.com/pricing
+
+### "Parallel AI API key invalid"
+
+```bash
+# Verify key in .env.local
+grep PARALLEL_API_KEY .env.local
+
+# Test key
+curl -s -X POST "https://api.parallel.ai/v1beta/search" \
+  -H "x-api-key: YOUR_KEY" \
+  -H "Content-Type: application/json" \
+  -H "parallel-beta: search-extract-2025-10-10" \
+  -d '{"objective": "test"}'
+```
+
+---
+
+## Next Steps
+
+✅ Setup complete? Try your [first feature](../QUICKSTART.md)
+
+📖 Learn the workflow in [AGENTS.md](../AGENTS.md)
+
+🛠️ Explore toolchain in [TOOLCHAIN.md](TOOLCHAIN.md)
+
+🎯 See examples in [EXAMPLES.md](EXAMPLES.md)
+
+---
+
+**Questions?** → [GitHub Discussions](https://github.com/harshanandak/forge/discussions)