# 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)