forge-workflow 0.0.1

package/docs/SETUP.md

@@ -0,0 +1,632 @@
+# 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/
+│   ├── WORKFLOW.md              # Complete guide
+│   ├── 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 [WORKFLOW.md](WORKFLOW.md)
+
+🛠️ Explore toolchain in [TOOLCHAIN.md](TOOLCHAIN.md)
+
+🎯 See examples in [EXAMPLES.md](EXAMPLES.md)
+
+---
+
+**Questions?** → [GitHub Discussions](https://github.com/harshanandak/forge/discussions)