forge-workflow 0.0.10 → 0.1.0-beta.2

package/docs/forge/TOOLCHAIN.md

@@ -0,0 +1,670 @@
+# Forge Toolchain Reference
+
+Complete reference for all tools integrated with the Forge workflow.
+
+## Overview
+
+Forge is a local runtime control plane that coordinates several tool surfaces:
+
+```text
+Forge runtime control plane
+  - workflow templates and stage skills
+  - local project state and protected surfaces
+  - kernel-backed issue wrappers and sync (Beads is an opt-out backend)
+  - validation, packaging, and release evidence
+  - review adapters and external service hooks
+  - harness projections for agent-specific commands, prompts, workflows, and skills
+```
+
+The default TDD-first workflow is a core template shipped by Forge. It is not the only runtime primitive. Toolchain docs should describe tools by the surface they support: setup, state, workflow stages, validation, review, release, sync, and recovery.
+
+---
+
+## Beads - Local Issue Tracking And Sync Projection
+
+**Package**: `@beads/bd`
+**Repository**: [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+**Purpose**: Distributed issue tracking designed for AI coding agents
+
+### Why Beads?
+
+- **Persists across sessions** - Issues survive context clearing, compaction, new chats
+- **Local-first** - Runtime state stays under local `.beads/` and does not dirty normal Git work
+- **Dependency tracking** - Know what blocks what
+- **Ready detection** - `forge ready` finds unblocked work automatically
+- **AI-optimized** - JSON output, semantic compaction, audit trails
+
+### Installation
+
+**Auto-installation** (Recommended):
+```bash
+bunx forge setup
+# Prompts: "Install Beads? (y/n)"
+# Automatically installs and initializes
+# On Windows: uses PowerShell installer (npm @beads/bd has an EPERM bug on Windows)
+```
+
+**Manual installation**:
+```bash
+# macOS / Linux (global)
+bun add -g @beads/bd
+bd init
+
+# macOS / Linux (local)
+bun add -d @beads/bd
+bunx bd init
+
+# Windows (global) — use PowerShell installer, NOT npm/bun add -g
+#
+# ⚠️  SECURITY WARNING: The one-liner below pipes remote content directly to execution.
+#     If the upstream repo, CDN, or transit is compromised, this runs arbitrary code.
+#     Prefer the "download + inspect" flow below for supply-chain safety.
+#
+# RECOMMENDED (safer — download, inspect, then run):
+$installer = "$env:TEMP\beads-install.ps1"
+irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 -OutFile $installer
+# Open $installer in a text editor and review before running
+# Get-Content $installer | less     # or: notepad $installer
+& $installer                         # execute after inspection
+bd init
+
+# CONVENIENCE (unsafe — reviewed installer only, skip if you don't trust the source):
+# # See the safer download-then-inspect flow in the Beads install section.
+# UNSAFE one-liner (only use if you trust the source and have reviewed it previously):
+# irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 -OutFile $env:TEMP\beads-install.ps1; & $env:TEMP\beads-install.ps1
+# bd init
+
+# Or with bunx (macOS/Linux, no install needed)
+bunx @beads/bd init
+```
+
+> **Windows note**: The `npm install -g @beads/bd` postinstall script uses `Expand-Archive`, which triggers an EPERM file-locking error on Windows (issue #1031, closed "not planned"). Use the PowerShell installer above instead.
+
+### File Structure
+
+After `bd init`, creates a local `.beads/` directory. Forge keeps this directory out of Git; `forge setup` writes local Git exclude rules under `.git/info/exclude` so downstream repositories do not need metadata-only commits.
+
+```
+.beads/
+├── issues.jsonl       # Local/exported issue data
+├── beads.db           # SQLite cache, when present
+├── metadata.json      # Local database metadata
+├── config.yaml        # Local Beads configuration
+├── interactions.jsonl # Local agent audit log
+└── .gitignore         # Local ignore guard for runtime files
+```
+
+Do not commit live `.beads/` runtime files. Shared team state must use the configured sync/server authority or an explicit projection/import path.
+
+For day-to-day issue workflows, prefer the Forge wrapper commands (`forge ready`,
+`forge create`, `forge update`, `forge close`, `forge sync`). Use `bd` directly
+for Beads capabilities Forge does not wrap yet, such as `bd init`, `bd comments`,
+`bd dep`, `bd blocked`, and `bd dolt *`.
+
+### Complete Command Reference
+
+#### Initialization
+
+```bash
+bd init                    # Initialize in project
+bd init --stealth          # Local-only (don't commit to repo)
+bd init --contributor      # Contributor mode
+bd init --prefix PROJ      # Custom issue prefix (PROJ-xxx)
+```
+
+#### Issue Management
+
+```bash
+# Create issues
+forge create "Title"                           # Basic issue
+forge create "Title" --type feature            # With type (feature, bug, chore, etc.)
+forge create "Title" --priority 1              # With priority (0=critical, 4=backlog)
+forge create "Title" -p 0 -l "urgent,backend"  # P0 with labels
+
+# View issues
+forge show <id>                   # Detailed view with audit trail
+forge list                        # All issues
+forge list --status open          # Filter by status
+forge list --priority 1           # Filter by priority
+forge list --assignee bob         # Filter by assignee
+forge list --label bug            # Filter by label (AND logic)
+forge list --label-any bug,urgent # Filter by label (OR logic)
+forge list --type feature         # Filter by type
+forge list --title-contains "auth" # Search titles
+forge list --limit 10             # Limit results
+
+# Update issues
+forge claim <id>                        # Claim work (sets in_progress)
+forge update <id> --priority 2          # Change priority
+forge update <id> --assignee bob        # Assign
+forge update <id> --title "New title"   # Update title
+forge update <id> --description "..."   # Update description
+forge update <id> --notes "..."         # Add notes
+forge update <id> --add-label urgent    # Add label
+
+# Complete issues
+forge close <id>                           # Close single issue
+forge close <id1> <id2> <id3>              # Close multiple (efficient)
+forge close <id> --reason "Completed auth" # Close with reason
+bd delete <id>                          # Delete issue
+bd delete <id> --cascade                # Delete with dependents
+```
+
+#### Workflow Commands
+
+```bash
+# Find work
+forge ready                     # Issues with NO open blockers (start here!)
+forge ready --priority 1        # Filter ready work by priority
+bd blocked                      # Issues that ARE blocked
+
+# Dependencies
+bd dep add <child> <parent>                    # child depends on parent (blocks)
+bd dep add <child> <parent> --type related     # Soft reference (no blocking)
+bd dep add <child> <parent> --type parent-child # Hierarchical
+bd dep remove <child> <parent>                 # Remove dependency
+bd dep tree <id>                               # Visualize dependency tree
+bd dep cycles                                  # Detect cycles
+
+# Comments
+bd comments <id>                # View comments
+bd comments add <id> "Comment text" # Add comment
+
+# Git sync
+forge sync                      # Pull + push Beads state through the Forge wrapper
+bd dolt status                  # Check Dolt sync/server status
+bd hooks install                # Install git hooks for auto-sync
+
+# Maintenance
+bd stats                        # Project statistics
+bd doctor                       # Check for issues
+bd admin compact --days 90      # Compact old closed issues
+```
+
+#### Issue Statuses
+
+- `open` - Not started
+- `in_progress` - Being worked on
+- `blocked` - Waiting on something
+- `completed` - Done
+- `on_hold` - Paused
+- `cancelled` - Won't do
+
+#### Priority Levels
+
+| Priority | Meaning | Usage |
+|----------|---------|-------|
+| 0 (P0) | Critical | Drop everything, fix now |
+| 1 (P1) | High | Do this sprint |
+| 2 (P2) | Medium | Planned work |
+| 3 (P3) | Low | Nice to have |
+| 4 (P4) | Backlog | Someday/maybe |
+
+#### Dependency Types
+
+| Type | Blocks Ready? | Use Case |
+|------|---------------|----------|
+| `blocks` | YES | Hard dependency |
+| `related` | NO | Soft reference |
+| `parent-child` | YES | Hierarchy |
+| `discovered-from` | NO | Found during work |
+
+### Session Workflow
+
+```bash
+# Start of session
+forge ready                 # What can I work on?
+forge show <id>             # Review the issue
+forge claim <id>
+
+# During work
+bd comments add <id> "Progress update"
+forge update <id> --notes "Found edge case"
+
+# End of session
+forge close <id>            # If done, or:
+forge update <id> --status blocked --comment "Needs API response"
+forge sync                  # Always sync at end!
+```
+
+---
+
+## MCP Servers
+
+### Context7 - Library Documentation
+
+**Package**: `@upstash/context7-mcp@2` (pin to major version, not `@latest`)
+**Purpose**: Up-to-date documentation and code examples for any programming library
+**Used in**: `/plan` stage (Phase 2 research); any library lookup
+
+Context7 provides current documentation that may be more recent than the AI's training data.
+
+**Installation**:
+
+**Claude Code**: Add to `.mcp.json` in your project root:
+
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "bunx",
+      "args": ["--bun", "@upstash/context7-mcp@2"]
+    }
+  }
+}
+```
+
+**Cursor**: Check Cursor Settings → MCP Servers for configuration options
+
+**Other agents**: If your agent supports MCP, configure using the JSON format above
+
+**Usage**:
+```
+# The AI will automatically use Context7 when you ask about libraries
+"How do I use React Query's useMutation hook?"
+"What's the latest Next.js App Router API?"
+"Show me Supabase RLS policy examples"
+```
+
+**When to use Context7**:
+- Before implementing a library feature
+- When official docs may have changed since AI training
+- To verify API signatures and patterns
+- For current best practices
+
+### grep.app - Code Search
+
+**Package**: `@ai-tools-all/grep_app_mcp` (recommended) or `@galprz/grep-mcp`
+**Website**: [grep.app](https://grep.app)
+**Purpose**: Search across 1M+ public GitHub repositories for real-world code examples
+**Used in**: `/plan` stage (Phase 2 research); finding implementation patterns
+
+grep.app provides code search across public GitHub repositories to find real-world examples and patterns.
+
+**Installation (Claude Code)**:
+
+Add to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "bunx",
+      "args": ["--bun", "@upstash/context7-mcp@2"]
+    },
+    "grep-app": {
+      "command": "bunx",
+      "args": ["--bun", "@ai-tools-all/grep_app_mcp"]
+    }
+  }
+}
+```
+
+**Usage**:
+```
+# The AI will use grep.app when you need real-world examples
+"Find examples of React useEffect cleanup patterns"
+"Show me how others implement JWT authentication in Express"
+"Search for rate limiting implementations in Node.js"
+```
+
+**When to use grep.app**:
+
+- Finding real-world implementation examples
+- Discovering coding patterns in production code
+- Validating implementation approaches
+- Learning from open source projects
+
+**Context7 vs grep.app**:
+
+| Tool           | Purpose                        | Use When                                  |
+|----------------|--------------------------------|-------------------------------------------|
+| **Context7**   | Official library documentation | You need API reference, official patterns |
+| **grep.app**   | Real code in the wild          | You want to see how others solve problems |
+
+---
+
+## External Services
+
+### Parallel AI - Web Research
+
+**Website**: [platform.parallel.ai](https://platform.parallel.ai)
+**Used in**: `/plan` stage (Phase 2 research)
+
+4 APIs for research:
+- **Search** - Web search with AI analysis
+- **Extract** - Scrape specific URLs
+- **Task** - Structured data enrichment
+- **Deep Research** - Multi-source analysis
+
+```bash
+# Setup
+# 1. Get key from https://platform.parallel.ai
+# 2. Add to .env.local
+PARALLEL_API_KEY=your-key
+
+# 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": "Next.js authentication best practices 2026"}'
+```
+
+---
+
+## Code Review Tools
+
+Choose ONE code review tool based on your needs:
+
+| Tool | Pricing | Best For | Setup |
+|------|---------|----------|-------|
+| **GitHub Code Quality** | FREE | All GitHub repos | Built-in, zero setup |
+| **CodeRabbit** | FREE (OSS) | Open source projects | GitHub App |
+| **Greptile** | $99+/mo | Enterprise | API key |
+
+### Option 1: GitHub Code Quality (FREE, Recommended)
+
+**Status**: Built-in to GitHub
+**Used in**: `/review` stage
+
+Zero setup required - GitHub's code quality features are enabled by default.
+
+Features:
+- Automatic code scanning
+- Dependency vulnerability alerts
+- Secret scanning
+- Code navigation
+
+### Option 2: CodeRabbit (FREE for Open Source)
+
+**Website**: [coderabbit.ai](https://coderabbit.ai)
+**Used in**: `/review` stage
+
+AI-powered code review with deep context understanding.
+
+```bash
+# Setup
+# 1. Go to https://coderabbit.ai
+# 2. Install the GitHub App
+# 3. Enable for your repositories
+
+# Configuration (optional)
+# Create .coderabbit.yaml in repo root
+```
+
+### Option 3: Greptile (Paid - Enterprise)
+
+**Website**: [greptile.com](https://greptile.com)
+**Used in**: `/review` stage
+
+Enterprise-grade AI code review that understands your codebase.
+
+```bash
+# Setup
+# 1. Get key from https://app.greptile.com
+# 2. Add to .env.local
+GREPTILE_API_KEY=your-key
+
+# 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"}'
+```
+
+---
+
+## Code Quality Tools
+
+Choose ONE code quality scanner based on your needs:
+
+| Tool | Pricing | Best For | Requirement |
+|------|---------|----------|-------------|
+| **ESLint** | FREE | All projects | Built-in |
+| **SonarCloud** | 50k LoC free | Cloud-first teams | API key |
+| **SonarQube Community** | FREE | Self-hosted, unlimited | Docker |
+
+### Option 1: ESLint Only (FREE, Recommended)
+
+**Status**: Built-in
+**Used in**: `/validate` stage
+
+No external server required - uses your project's linting configuration.
+
+```bash
+# Already configured via package.json or eslint.config.js
+bun run lint
+```
+
+### Option 2: SonarCloud (Cloud-Hosted)
+
+**Website**: [sonarcloud.io](https://sonarcloud.io)
+**Used in**: `/validate` stage
+**Free Tier**: 50,000 lines of code
+
+Static analysis for bugs, vulnerabilities, code smells.
+
+```bash
+# Setup
+# 1. Create project at https://sonarcloud.io
+# 2. Get token from Security settings
+# 3. Add to .env.local
+SONAR_TOKEN=your-token
+SONAR_ORGANIZATION=your-org
+SONAR_PROJECT_KEY=your-project
+
+# 4. Create sonar-project.properties
+echo "sonar.organization=$SONAR_ORGANIZATION
+sonar.projectKey=$SONAR_PROJECT_KEY
+sonar.sources=src" > sonar-project.properties
+
+# 5. Run analysis
+bunx sonarqube-scanner
+```
+
+### Option 3: SonarQube Community (Self-Hosted, FREE)
+
+**Website**: [sonarqube.org](https://www.sonarsource.com/products/sonarqube/)
+**Used in**: `/validate` stage
+**Pricing**: FREE, unlimited lines of code
+
+Self-hosted code quality analysis - no cloud dependency.
+
+```bash
+# Setup with Docker
+docker run -d --name sonarqube \
+  -p 9000:9000 \
+  sonarqube:community
+
+# Access at http://localhost:9000
+# Default credentials: admin/admin
+
+# Add to .env.local
+SONARQUBE_URL=http://localhost:9000
+SONARQUBE_TOKEN=your-token  # Generate in SonarQube UI
+
+# Create sonar-project.properties
+echo "sonar.host.url=$SONARQUBE_URL
+sonar.login=$SONARQUBE_TOKEN
+sonar.projectKey=your-project
+sonar.sources=src" > sonar-project.properties
+
+# Run analysis
+bunx sonarqube-scanner
+```
+
+**Docker Compose (Production)**:
+```yaml
+# docker-compose.yml
+version: '3'
+services:
+  sonarqube:
+    image: sonarqube:community
+    ports:
+      - "9000:9000"
+    environment:
+      - SONAR_ES_BOOTSTRAP_CHECKS_DISABLE=true
+    volumes:
+      - sonarqube_data:/opt/sonarqube/data
+      - sonarqube_logs:/opt/sonarqube/logs
+
+volumes:
+  sonarqube_data:
+  sonarqube_logs:
+```
+
+---
+
+### GitHub CLI - PR Workflow
+
+**Installation**: [cli.github.com](https://cli.github.com)
+**Used in**: `/ship` and `/review` stages
+
+```bash
+# Install
+# macOS: brew install gh
+# Windows: winget install GitHub.cli
+# Linux: sudo apt install gh
+
+# Authenticate
+gh auth login
+
+# Common commands
+gh pr create --title "..." --body "..."
+gh pr view <number>
+gh pr checks <number>
+gh pr merge <number> --squash --delete-branch
+gh issue create --title "..." --body "..."
+```
+
+---
+
+## Global CLI Tools
+
+### Beads (`bd`) — Minimum Version
+
+**Minimum version**: v0.49.x
+**Check installed version**:
+```bash
+bd --version
+```
+
+**Install / Update**:
+```bash
+# macOS / Linux
+bun add -g @beads/bd
+
+# Windows — use PowerShell installer (npm has EPERM bug)
+# See the safer download-then-inspect flow in the Beads install section.
+# UNSAFE one-liner (only use if you trust the source and have reviewed it previously):
+# irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 -OutFile $env:TEMP\beads-install.ps1; & $env:TEMP\beads-install.ps1
+```
+
+> **Why Forge + Beads?** Forge wraps the supported day-to-day issue workflow
+> (`forge ready`, `forge create`, `forge close`, `forge sync`) while Beads
+> remains the underlying store for initialization, dependencies, comments, and
+> Dolt-backed sync internals.
+
+---
+
+## Default Workflow Template Mapping
+
+This table maps tools to the default workflow template. It is not the complete Forge product model and it is not a requirement that every project use every stage.
+
+| Stage | Tools Used |
+|-------|------------|
+| `/status` | `forge ready`, `forge list`, `git status` |
+| `/plan` (Phase 2) | Parallel AI, Context7, grep.app, codebase exploration |
+| `/plan` | `forge create`, `git checkout -b` |
+| `/dev` | Tests, code, `forge update`, `/tasks save` |
+| `/validate` | Type check, lint, tests, SonarCloud |
+| `/ship` | `forge close`, `gh pr create` |
+| `/review` | `gh pr view`, Greptile, SonarCloud |
+| `/verify` | Documentation cross-check |
+
+Pre-merge is not a stage. Its work (`forge sync`, doc updates, hand off PR) runs inside the `/ship` and `/review` stages as an embedded documentation-and-handoff gate.
+
+---
+
+## Quick Reference Card
+
+### Beads (Issue Tracking)
+
+```bash
+bd init                     # Initialize
+forge ready                 # Find unblocked work
+forge create "Title"        # Create issue
+forge show <id>             # View details
+forge update <id> --status X   # Update status
+bd dep add <a> <b>          # a depends on b
+forge close <id>            # Complete
+forge sync                  # Beads sync
+```
+
+### GitHub CLI
+
+```bash
+gh auth login               # Authenticate
+gh pr create                # Create PR
+gh pr view <n>              # View PR
+gh pr checks <n>            # Check status
+gh pr merge <n> --squash    # Merge
+```
+
+---
+
+## Troubleshooting
+
+### Beads
+
+**"bd: command not found"**
+```bash
+# macOS / Linux
+bun add -g @beads/bd
+# Or use bunx @beads/bd <command>
+
+# Windows — use PowerShell installer
+# See the safer download-then-inspect flow in the Beads install section.
+# UNSAFE one-liner (only use if you trust the source and have reviewed it previously):
+# irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 -OutFile $env:TEMP\beads-install.ps1; & $env:TEMP\beads-install.ps1
+```
+
+**Windows EPERM error during `npm install -g @beads/bd`**
+```bash
+# npm @beads/bd has a known EPERM bug on Windows (Issue #1031)
+# Use the PowerShell installer instead:
+# See the safer download-then-inspect flow in the Beads install section.
+# UNSAFE one-liner (only use if you trust the source and have reviewed it previously):
+# irm https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1 -OutFile $env:TEMP\beads-install.ps1; & $env:TEMP\beads-install.ps1
+```
+
+**"database locked"**
+```bash
+forge sync
+```
+
+**Issues not showing after git pull**
+```bash
+forge sync  # Re-syncs Beads state through the Forge wrapper
+```
+
+### GitHub CLI
+
+**"gh: not authenticated"**
+```bash
+gh auth login
+gh auth status
+```
+
+---
+
+## Resources
+
+- **Beads**: [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+- **Parallel AI**: [platform.parallel.ai](https://platform.parallel.ai)
+- **Greptile**: [greptile.com](https://greptile.com)
+- **SonarCloud**: [sonarcloud.io](https://sonarcloud.io)
+- **GitHub CLI**: [cli.github.com](https://cli.github.com)