npm - forge-workflow - Versions diffs - 1.4.0 → 1.4.2 - Mend

forge-workflow 1.4.0 → 1.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/.claude/settings.json +4 -1
package/.claude/settings.local.json +21 -1
package/README.md +217 -761
package/docs/EXAMPLES.md +750 -0
package/docs/README-v1.3.md +860 -0
package/docs/SETUP.md +723 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,860 +1,316 @@
 # Forge
-A 9-stage TDD-first workflow for **ALL AI coding agents**. Ship features with confidence using test-driven development, research-first planning, and comprehensive documentation.
+Ship features with confidence using a 9-stage TDD-first workflow for AI coding agents.
 ```
-/status -> /research -> /plan -> /dev -> /check -> /ship -> /review -> /merge -> /verify
+/status → /research → /plan → /dev → /check → /ship → /review → /merge → /verify
 ```
-## Why Forge?
-- **TDD-First**: Write tests before code (RED-GREEN-REFACTOR)
-- **Research-First**: Understand before building, document decisions
-- **Security Built-In**: OWASP Top 10 analysis for every feature
-- **Multi-Session**: Track work across sessions with Beads
-- **Strategic Planning**: Use OpenSpec for architecture changes
-- **Universal**: Works with 11+ AI coding agents
-## Supported AI Coding Agents
-Forge works with **all major AI coding agents** using the universal AGENTS.md standard:
-| Agent | Status | Primary Config | Commands Location |
-|-------|--------|----------------|-------------------|
-| **Claude Code** | Full | `CLAUDE.md` | `.claude/commands/` |
-| **Google Antigravity** | Full | `GEMINI.md` | `.agent/workflows/` |
-| **Cursor** | Full | `.cursorrules` | `.cursor/rules/` |
-| **Windsurf** | Full | `.windsurfrules` | `.windsurf/workflows/` |
-| **Kilo Code** | Full | `AGENTS.md` | `.kilocode/workflows/` |
-| **OpenCode** | Full | `AGENTS.md` | `.opencode/commands/` |
-| **Continue** | Full | `.continuerules` | `.continue/prompts/` |
-| **GitHub Copilot** | Full | `.github/copilot-instructions.md` | `.github/prompts/` |
-| **Cline** | Full | `.clinerules` | Via instructions |
-| **Roo Code** | Full | `.clinerules` | `.roo/commands/` |
-| **Aider** | Full | `AGENTS.md` | Via instructions |
+✅ **TDD-First**: Write tests before code
+✅ **Research-First**: Understand before building
+✅ **Universal**: Works with 11+ AI agents
-## Installation
-### Option 1: npm (Recommended)
-```bash
-# Step 1: Install the package (minimal: AGENTS.md + docs)
-npm install forge-workflow
-# Step 2: Configure for your agents (interactive)
-npx forge setup
-```
-Or specify agents directly:
-```bash
-# Install for specific agents
-npx forge setup --agents claude,cursor,windsurf
+---
-# Install for all agents
-npx forge setup --all
-```
+## Quick Example
-### Option 2: curl (Interactive)
+**Adding a login button with Forge:**
 ```bash
-curl -fsSL https://raw.githubusercontent.com/harshanandak/forge/main/install.sh | bash
+/research login-button    # AI researches best practices + security
+/plan login-button        # Creates plan, branch, tracking issue
+/dev                      # TDD: RED → GREEN → REFACTOR cycles
+/check                    # Type check + lint + tests + security scan
+/ship                     # Create PR with full documentation
 ```
-### Option 3: bun
+**Result**: Feature shipped with tests, security validated, fully documented.
-```bash
-bun add forge-workflow
-bunx forge setup
-```
-## The Toolchain
+**Without Forge** (chaotic):
+- Code first, tests later (or never)
+- No research or planning
+- Security issues found in production
+- Documentation forgotten
-Forge integrates with three powerful tools for complete workflow management:
+**With Forge** (systematic):
+- Tests written BEFORE code (TDD)
+- Research-backed decisions
+- OWASP Top 10 analysis built-in
+- Documentation at every stage
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        FORGE TOOLCHAIN                          │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│  ┌─────────────┐   ┌─────────────┐   ┌─────────────────────┐   │
-│  │   BEADS     │   │  OPENSPEC   │   │    CLAUDE TASKS     │   │
-│  │             │   │             │   │                     │   │
-│  │ Issue       │   │ Proposal    │   │ Save/Resume         │   │
-│  │ Tracking    │   │ System      │   │ Task State          │   │
-│  │             │   │             │   │                     │   │
-│  │ bd create   │   │ openspec    │   │ /tasks save         │   │
-│  │ bd ready    │   │ proposal    │   │ /tasks resume       │   │
-│  │ bd close    │   │ create      │   │ /tasks list         │   │
-│  └─────────────┘   └─────────────┘   └─────────────────────┘   │
-│        │                 │                     │                │
-│        └─────────────────┴─────────────────────┘                │
-│                          │                                      │
-│                    ┌─────▼─────┐                                │
-│                    │   FORGE   │                                │
-│                    │  9-Stage  │                                │
-│                    │  Workflow │                                │
-│                    └───────────┘                                │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
+→ [See complete walkthrough in QUICKSTART.md](QUICKSTART.md)
-### Beads - Issue Tracking Across Sessions
+---
-[Beads](https://github.com/steveyegge/beads) provides git-backed, distributed issue tracking designed for AI coding agents.
+## Installation
 ```bash
-# Install
-npm install -g @beads/bd
-# Initialize in your project
-bd init
-# Find work ready to start (no blockers!)
-bd ready
-# Create an issue
-bd create "Add user authentication" --type feature --priority 2
-# View issue details
-bd show <id>
-# Update status
-bd update <id> --status in_progress
-# Add dependencies (child depends on parent)
-bd dep add <child> <parent>
-# Add comments during work
-bd comments <id> "Progress: login working, starting signup"
-# Complete work
-bd close <id> --reason "Implemented with JWT"
+# Step 1: Install the package
+npm install forge-workflow
-# Sync with git (ALWAYS at session end!)
-bd sync
+# Step 2: Setup for your AI agent
+npx forge setup
 ```
-**Why Beads?**
-- **Persists across sessions** - Issues survive context clearing, compaction, new chats
-- **Git-backed** - Version controlled like code, mergeable, team-shareable
-- **Dependency tracking** - Know what blocks what with `bd blocked`
-- **Ready detection** - `bd ready` finds unblocked work automatically
-- **AI-optimized** - JSON output, semantic compaction, audit trails
-See [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) for complete Beads command reference.
+**That's it!** Forge will:
+- Create AGENTS.md (universal instructions)
+- Setup agent-specific files (Claude, Cursor, etc.)
+- Create docs/ folder with guides
-### OpenSpec - Spec-Driven Development
-[OpenSpec](https://github.com/Fission-AI/OpenSpec) provides spec-driven development for AI-assisted workflows.
-```bash
-# Install (requires Node.js 20.19+)
-npm install -g @fission-ai/openspec
-# Initialize
-openspec init
-# In AI assistant (Claude Code, Cursor, Windsurf):
-/opsx:new          # Start a new change
-/opsx:ff           # Fast-forward: generate all planning docs
-/opsx:apply        # Implement tasks
-/opsx:verify       # Validate implementation
-/opsx:archive      # Complete and archive
-# Creates:
-# openspec/changes/[name]/
-#   ├── proposal.md      # Intent, scope, rationale
-#   ├── design.md        # Technical approach
-#   ├── tasks.md         # Implementation checklist
-#   └── specs/           # Delta specifications (ADDED/MODIFIED/REMOVED)
-```
+**Prerequisites**: Node.js, Git, GitHub account
+**Optional tools**: Beads (issue tracking), OpenSpec (architecture proposals)
-**When to use OpenSpec:**
+→ [Detailed setup guide for all agents](docs/SETUP.md)
-| Scope | Use OpenSpec? | Example |
-|-------|---------------|---------|
-| **Tactical** (< 1 day) | No | Bug fix, small feature |
-| **Strategic** (architecture) | Yes | New service, major refactor |
-| **Breaking changes** | Yes | API changes, schema migrations |
-| **Multi-session work** | Yes | Large features |
+---
-**Workflow:**
-```bash
-# 1. Start change (in AI assistant)
-/opsx:new
-# Describe: "Add payment processing with Stripe"
-# 2. Generate all planning docs
-/opsx:ff
-# Creates proposal.md, design.md, tasks.md, specs/
-# 3. Implement
-/opsx:apply
-# AI writes code following tasks.md
-# 4. Validate and finalize
-/opsx:verify          # Confirm implementation matches specs
-openspec sync         # Merge deltas into main specs
-openspec archive name # Move to archive
-```
+## The 9 Stages
-See [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) for complete OpenSpec reference.
+| Stage | Command | Purpose |
+|-------|---------|---------|
+| **1. Status** | `/status` | Check current context, active work |
+| **2. Research** | `/research` | Deep research with AI, document findings |
+| **3. Plan** | `/plan` | Create plan + branch + tracking |
+| **4. Dev** | `/dev` | TDD development (RED-GREEN-REFACTOR) |
+| **5. Check** | `/check` | Validate: types, lint, tests, security |
+| **6. Ship** | `/ship` | Create PR with documentation |
+| **7. Review** | `/review` | Address ALL PR feedback |
+| **8. Merge** | `/merge` | Update docs, merge, cleanup |
+| **9. Verify** | `/verify` | Final documentation check |
-### Claude Tasks - Save and Resume Work
+**Full workflow guide**: [docs/WORKFLOW.md](docs/WORKFLOW.md)
-Claude Code's built-in task system lets you save work state and resume later.
+---
+## Supported AI Agents
+Works with **11+ AI coding agents**:
+| Agent | Status | Setup Time |
+|-------|--------|------------|
+| **Claude Code** | ✅ Full support | 30 seconds |
+| **Cursor** | ✅ Full support | 30 seconds |
+| **Windsurf** | ✅ Full support | 30 seconds |
+| **GitHub Copilot** | ✅ Full support | 30 seconds |
+| **Google Antigravity** | ✅ Full support | 30 seconds |
+| **Kilo Code** | ✅ Full support | 30 seconds |
+| **OpenCode** | ✅ Full support | 30 seconds |
+| **Continue** | ✅ Full support | 30 seconds |
+| **Cline** | ✅ Full support | 30 seconds |
+| **Roo Code** | ✅ Full support | 30 seconds |
+| **Aider** | ✅ Full support | 30 seconds |
+**Setup for specific agents**:
 ```bash
-# Save current task state
-/tasks save "implementing auth flow"
-# List saved tasks
-/tasks list
-# Resume a saved task
-/tasks resume <task-id>
-# Delete a task
-/tasks delete <task-id>
+npx forge setup --agents claude,cursor,windsurf
 ```
-**When to use Claude Tasks:**
-- Taking a break mid-implementation
-- Switching between features
-- Preserving context before `/clear`
-- Handoff to another session
-## The 9 Stages
-| Stage | Command | What It Does | Tools Used |
-|-------|---------|--------------|------------|
-| 1 | `/status` | Check current context | Beads, Git |
-| 2 | `/research` | Deep research, document findings | Web search, Codebase |
-| 3 | `/plan` | Create plan, branch, tracking | Beads, OpenSpec |
-| 4 | `/dev` | TDD development (RED-GREEN-REFACTOR) | Tests, Code |
-| 5 | `/check` | Validation (type/lint/security/tests) | CI tools |
-| 6 | `/ship` | Create PR with documentation | GitHub CLI |
-| 7 | `/review` | Address ALL PR feedback | GitHub, Greptile |
-| 8 | `/merge` | Update docs, merge, cleanup | Git |
-| 9 | `/verify` | Final documentation check | Docs |
-## Complete Workflow Example
+**Setup for all agents**:
 ```bash
-# ═══════════════════════════════════════════════════════════
-# STAGE 1: STATUS - Where are we?
-# ═══════════════════════════════════════════════════════════
-/status
-# Checks:
-# - bd ready (Beads issues ready to work)
-# - bd list --status in_progress (active work)
-# - git status (branch state)
-# - openspec list --active (pending proposals)
-# ═══════════════════════════════════════════════════════════
-# STAGE 2: RESEARCH - Understand before building
-# ═══════════════════════════════════════════════════════════
-/research user-authentication
-# Creates: docs/research/user-authentication.md
-# Contains:
-# - Codebase analysis (existing patterns)
-# - Web research (best practices, security)
-# - OWASP Top 10 analysis
-# - Key decisions with reasoning
-# - TDD test scenarios (identified UPFRONT)
-# ═══════════════════════════════════════════════════════════
-# STAGE 3: PLAN - Create formal plan
-# ═══════════════════════════════════════════════════════════
-/plan user-authentication
-# If TACTICAL (< 1 day):
-bd create "Add user authentication"
-git checkout -b feat/user-authentication
-# If STRATEGIC (architecture change):
-openspec proposal create user-authentication
-# Write proposal.md, tasks.md, design.md
-openspec validate user-authentication --strict
-bd create "User auth (see openspec/changes/user-authentication)"
-git checkout -b feat/user-authentication
-# Create PR for proposal approval first!
-# ═══════════════════════════════════════════════════════════
-# STAGE 4: DEV - TDD Implementation
-# ═══════════════════════════════════════════════════════════
-/dev
-# TDD Cycle (repeat for each feature):
-# RED:    Write failing test
-# GREEN:  Make it pass (minimal code)
-# REFACTOR: Clean up
-# COMMIT: git commit after each GREEN
-bd update <id> --status in_progress
-# If taking a break:
-/tasks save "auth flow - completed login, starting signup"
-# ═══════════════════════════════════════════════════════════
-# STAGE 5: CHECK - Validate everything
-# ═══════════════════════════════════════════════════════════
-/check
-# Runs:
-# - Type checking (tsc/typecheck)
-# - Linting (eslint)
-# - Unit tests
-# - Integration tests
-# - E2E tests
-# - Security scan
-# If fails:
-bd update <id> --status blocked --comment "Type errors in auth.ts"
-# ═══════════════════════════════════════════════════════════
-# STAGE 6: SHIP - Create PR
-# ═══════════════════════════════════════════════════════════
-/ship
-bd update <id> --status done
-git push -u origin feat/user-authentication
-gh pr create --title "feat: user authentication" --body "
-## Summary
-- JWT-based auth with refresh tokens
-- Login/signup/logout flows
-- Password reset via email
-## Research
-See: docs/research/user-authentication.md
-## Beads Issue
-Closes: beads-abc123
-## Test Coverage
-- 45 unit tests
-- 12 integration tests
-- 8 E2E tests
-"
-# ═══════════════════════════════════════════════════════════
-# STAGE 7: REVIEW - Address ALL feedback
-# ═══════════════════════════════════════════════════════════
-/review 123
-# Address:
-# - GitHub Actions failures
-# - Greptile comments
-# - SonarCloud issues
-# - Human reviewer comments
-# Fix, commit, push
-git commit -m "fix: address PR review feedback"
-git push
-# ═══════════════════════════════════════════════════════════
-# STAGE 8: MERGE - Complete the work
-# ═══════════════════════════════════════════════════════════
-/merge 123
-# Update docs BEFORE merge:
-# - docs/planning/PROGRESS.md
-# - API documentation
-# - README if user-facing
-gh pr merge 123 --squash --delete-branch
-# If OpenSpec was used:
-openspec archive user-authentication
-bd sync
-git checkout main && git pull
-# ═══════════════════════════════════════════════════════════
-# STAGE 9: VERIFY - Final documentation check
-# ═══════════════════════════════════════════════════════════
-/verify
-# Verify:
-# - PROGRESS.md updated
-# - API docs current
-# - README examples work
-# - Cross-references valid
-# Done! Back to /status for next task
+npx forge setup --all
 ```
-## Directory Structure
+→ [Agent-specific setup instructions](docs/SETUP.md)
-After running `npx forge setup`, only selected agents are configured:
-```
-your-project/
-├── AGENTS.md                    # Universal standard (always created)
-├── CLAUDE.md                    # -> linked to AGENTS.md (if Claude selected)
-├── GEMINI.md                    # -> linked (if Antigravity selected)
-├── .cursorrules                 # -> linked (if Cursor selected)
-├── .windsurfrules               # -> linked (if Windsurf selected)
-├── .clinerules                  # -> linked (if Cline/Roo selected)
-│
-├── .beads/                      # Beads issue tracking (if bd init)
-│   └── issues/
-│
-├── openspec/                    # OpenSpec proposals (if openspec init)
-│   ├── specs/
-│   └── changes/
-│
-├── .claude/                     # Claude Code (if selected)
-│   ├── commands/                # 9 workflow commands
-│   ├── rules/
-│   └── skills/forge-workflow/
-│
-├── .cursor/                     # Cursor (if selected)
-│   ├── rules/forge-workflow.mdc
-│   └── skills/forge-workflow/
-│
-├── .windsurf/                   # Windsurf (if selected)
-│   ├── workflows/
-│   └── skills/forge-workflow/
-│
-└── docs/
-    ├── planning/PROGRESS.md     # Project progress
-    ├── research/                # Research documents
-    │   └── TEMPLATE.md
-    └── WORKFLOW.md              # Complete guide
-```
+---
-## External Services & API Tokens
+## What Makes Forge Different
-Forge integrates with external services for enhanced capabilities. **Most tools have FREE alternatives!**
+### 1. TDD-First Development
+Tests are written **BEFORE** code, every single time:
+- **RED**: Write a failing test
+- **GREEN**: Write minimal code to pass
+- **REFACTOR**: Clean up and commit
+- **REPEAT**: Next feature
-### Code Review Options (Choose One)
+No feature ships without tests. Period.
-| Tool | Pricing | Best For | Setup |
-|------|---------|----------|-------|
-| **GitHub Code Quality** | FREE | All GitHub repos | Built-in, zero setup ✓ |
-| **CodeRabbit** | FREE (OSS) | Open source | GitHub App |
-| **Greptile** | $99+/mo | Enterprise | API key |
+### 2. Research-First Planning
+AI researches best practices before you write a line of code:
+- Web search for latest patterns
+- OWASP Top 10 security analysis
+- Codebase pattern analysis
+- Decisions documented with evidence
-**Recommended**: Start with GitHub Code Quality (free, already enabled).
+Saves hours of debugging and refactoring later.
-### Code Quality Options (Choose One)
+### 3. Universal Compatibility
+One workflow, works with ALL major AI agents:
+- Single `AGENTS.md` file (universal standard)
+- Agent-specific enhancements (slash commands, skills)
+- Git-backed persistence (Beads)
+- No vendor lock-in
-| Tool | Pricing | Best For | Setup |
-|------|---------|----------|-------|
-| **ESLint** | FREE | All projects | Built-in ✓ |
-| **SonarCloud** | 50k LoC free | Cloud-first | API key |
-| **SonarQube Community** | FREE | Self-hosted | Docker |
+Switch agents anytime without changing your workflow.
-**Recommended**: Start with ESLint (free, already in your project).
+---
-Store API tokens in `.env.local`:
+## The Toolchain
+Forge integrates with powerful tools:
+```
+┌──────────────────────────────────────────────┐
+│              FORGE TOOLCHAIN                 │
+├──────────────────────────────────────────────┤
+│                                              │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
+│  │  BEADS   │  │ OPENSPEC │  │  GITHUB  │   │
+│  │  Issue   │  │ Proposal │  │    PR    │   │
+│  │ Tracking │  │  System  │  │ Workflow │   │
+│  └──────────┘  └──────────┘  └──────────┘   │
+│       │              │              │        │
+│       └──────────────┴──────────────┘        │
+│                      │                       │
+│                ┌─────▼─────┐                 │
+│                │   FORGE   │                 │
+│                │ 9-Stage   │                 │
+│                │ Workflow  │                 │
+│                └───────────┘                 │
+│                                              │
+└──────────────────────────────────────────────┘
+```
+**All tools are optional** - Forge works standalone.
+**Beads** (optional): Git-backed issue tracking that survives context clearing
 ```bash
-# .env.local (add to .gitignore!)
-# Code Review Tool Selection
-CODE_REVIEW_TOOL=github-code-quality  # or: coderabbit, greptile, none
-# Code Quality Tool Selection
-CODE_QUALITY_TOOL=eslint  # or: sonarcloud, sonarqube, none
-# Required for PR workflow
-GITHUB_TOKEN=ghp_xxxxxxxxxxxx
-# Parallel AI - Deep web research (/research stage, optional)
-PARALLEL_API_KEY=your-parallel-ai-key
-# Greptile - AI code review (only if CODE_REVIEW_TOOL=greptile)
-GREPTILE_API_KEY=your-greptile-key
-# SonarCloud (only if CODE_QUALITY_TOOL=sonarcloud)
-SONAR_TOKEN=your-sonarcloud-token
-SONAR_ORGANIZATION=your-org
-SONAR_PROJECT_KEY=your-project-key
-# SonarQube Self-Hosted (only if CODE_QUALITY_TOOL=sonarqube)
-SONARQUBE_URL=http://localhost:9000
-SONARQUBE_TOKEN=your-token
+npm install -g @beads/bd && bd init
 ```
-### Service Setup
-| Service | Pricing | Purpose | Get Token | Used In |
-|---------|---------|---------|-----------|---------|
-| **GitHub CLI** | FREE | PR workflow | `gh auth login` | `/ship`, `/review`, `/merge` |
-| **GitHub Code Quality** | FREE | Code review | Built-in | `/review` |
-| **CodeRabbit** | FREE (OSS) | AI code review | [coderabbit.ai](https://coderabbit.ai) | `/review` |
-| **Greptile** | $99+/mo | Enterprise review | [greptile.com](https://greptile.com) | `/review` |
-| **ESLint** | FREE | Linting | Built-in | `/check` |
-| **SonarCloud** | 50k LoC free | Cloud quality | [sonarcloud.io](https://sonarcloud.io) | `/check` |
-| **SonarQube** | FREE | Self-hosted quality | Docker | `/check` |
-| **Parallel AI** | Paid | Web research | [platform.parallel.ai](https://platform.parallel.ai) | `/research` |
-### Code Review Setup
-**Option 1: GitHub Code Quality (FREE, Recommended)**
-Zero setup required - GitHub's built-in code quality features are already enabled.
-**Option 2: CodeRabbit (FREE for Open Source)**
+**OpenSpec** (optional): Spec-driven development for architecture changes
 ```bash
-# 1. Go to https://coderabbit.ai
-# 2. Install the GitHub App
-# 3. Enable for your repositories
-# That's it! CodeRabbit will review PRs automatically.
+npm install -g @fission-ai/openspec && openspec init
 ```
-**Option 3: Greptile (Paid - Enterprise)**
+**GitHub CLI** (recommended): Required for PR workflow
 ```bash
-# 1. Get API key from https://app.greptile.com
-# 2. Add to .env.local
-GREPTILE_API_KEY=your-key
-# 3. Index your 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"}'
+gh auth login
 ```
-### Code Quality Setup
+→ [Complete toolchain guide](docs/TOOLCHAIN.md)
-**Option 1: ESLint Only (FREE, Recommended)**
+---
-Already configured in your project - no additional setup needed.
+## Real-World Examples
-```bash
-npm run lint  # or bun run lint
-```
-**Option 2: SonarCloud (Cloud-Hosted)**
+### Example 1: Simple Feature (15 minutes)
+**Task**: Add a health check endpoint
 ```bash
-# 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. Add sonar-project.properties
-echo "sonar.organization=$SONAR_ORGANIZATION
-sonar.projectKey=$SONAR_PROJECT_KEY
-sonar.sources=src" > sonar-project.properties
-# 5. Run analysis (in CI or locally)
-npx sonarqube-scanner
+/research health-check-endpoint  # 2 min: Research patterns
+/plan health-check-endpoint      # 1 min: Create plan + branch
+/dev                             # 8 min: TDD implementation
+/check                           # 2 min: All validations pass
+/ship                            # 2 min: PR created
 ```
-**Option 3: SonarQube Community (FREE, Self-Hosted)**
+### Example 2: Bug Fix with Security (20 minutes)
+**Task**: Fix SQL injection vulnerability
 ```bash
-# 1. Start SonarQube with Docker
-docker run -d --name sonarqube -p 9000:9000 sonarqube:community
-# 2. Access at http://localhost:9000 (admin/admin)
-# 3. Generate token in SonarQube UI
-# 4. Add to .env.local
-SONARQUBE_URL=http://localhost:9000
-SONARQUBE_TOKEN=your-token
-# 5. Add sonar-project.properties
-echo "sonar.host.url=http://localhost:9000
-sonar.login=your-token
-sonar.projectKey=your-project
-sonar.sources=src" > sonar-project.properties
-# 6. Run analysis
-npx sonarqube-scanner
+/research sql-injection-fix      # 5 min: OWASP research
+/plan sql-injection-fix          # 2 min: Plan + branch
+/dev                             # 8 min: Fix + tests
+/check                           # 3 min: Security scan
+/ship                            # 2 min: PR with security notes
 ```
-### Research Tool Setup
-**Parallel AI (Optional - Paid)**
+### Example 3: Architecture Change (2-3 days)
+**Task**: Add authentication system
 ```bash
-# 1. Get API key from https://platform.parallel.ai
-# 2. Add to .env.local
-PARALLEL_API_KEY=your-key
-# 3. Test with curl
-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"}'
+/research user-authentication    # 30 min: Deep research
+/plan user-authentication        # 60 min: OpenSpec proposal
+# → Create PR for proposal approval first
+/dev                             # 1-2 days: TDD implementation
+/check                           # 30 min: Full validation
+/ship                            # 15 min: PR with docs
+/review                          # Varies: Address feedback
+/merge                           # 15 min: Merge + cleanup
+/verify                          # 15 min: Final check
 ```
-### Loading Tokens
+→ [More examples in docs/EXAMPLES.md](docs/EXAMPLES.md)
-Forge includes a helper script:
-```bash
-# .claude/scripts/load-env.sh
-source .claude/scripts/load-env.sh
+---
-# Or manually
-export $(grep -v '^#' .env.local | xargs)
-```
+## Core Principles
-### Security Notes
+**TDD-First**: Tests before code, always
+**Research-First**: Understand before building
+**Security Built-In**: OWASP Top 10 for every feature
+**Documentation Progressive**: Update at each stage
+**Multi-Session**: Work persists across sessions
-- **NEVER commit `.env.local`** - add to `.gitignore`
-- Use GitHub Secrets for CI/CD
-- Rotate tokens periodically
-- Use least-privilege tokens where possible
+→ [Read the philosophy in docs/WORKFLOW.md](docs/WORKFLOW.md)
-## Prerequisites
+---
-### Required
+## Next Steps
-- **Git** - Version control
-- **GitHub CLI** - For PR workflow
-  ```bash
-  # macOS
-  brew install gh && gh auth login
+📚 **New to Forge?**
+→ [QUICKSTART.md](QUICKSTART.md) - Your first feature in 5 minutes
-  # Windows
-  winget install GitHub.cli && gh auth login
+📖 **Learn the workflow**
+→ [docs/WORKFLOW.md](docs/WORKFLOW.md) - Complete guide with examples
-  # Linux
-  sudo apt install gh && gh auth login
-  ```
+🛠️ **Setup the toolchain**
+→ [docs/TOOLCHAIN.md](docs/TOOLCHAIN.md) - Beads, OpenSpec, GitHub CLI
-### Recommended
+🎯 **See real examples**
+→ [docs/EXAMPLES.md](docs/EXAMPLES.md) - Real-world use cases
-- **Beads** - Issue tracking across sessions
-  ```bash
-  npm install -g @beads/bd
-  bd init
-  ```
+💬 **Have questions?**
+→ [GitHub Discussions](https://github.com/harshanandak/forge/discussions)
-### Optional
+🐛 **Found a bug?**
+→ [GitHub Issues](https://github.com/harshanandak/forge/issues)
-- **OpenSpec** - Spec-driven development (requires Node.js 20.19+)
-  ```bash
-  npm install -g @fission-ai/openspec
-  openspec init
-  ```
+---
 ## Quick Reference
-### Beads Commands
-```bash
-bd init                          # Initialize in project
-bd ready                         # Show work with no blockers (start here!)
-bd create "title" -p 2           # Create issue with priority
-bd show <id>                     # View issue details + audit trail
-bd list --status open            # List open issues
-bd update <id> --status X        # Update status
-bd dep add <child> <parent>      # child depends on parent
-bd comments <id> "note"          # Add comment
-bd close <id>                    # Complete issue
-bd blocked                       # Show blocked issues
-bd sync                          # Sync with git (always at session end!)
-```
-### OpenSpec Commands (AI Slash Commands)
-```bash
-/opsx:new                        # Start new change
-/opsx:ff                         # Fast-forward: generate all docs
-/opsx:apply                      # Implement tasks
-/opsx:verify                     # Validate implementation
-/opsx:sync                       # Merge delta specs
-/opsx:archive                    # Complete and archive
-```
-### OpenSpec Commands (CLI)
-```bash
-openspec init                    # Initialize
-openspec list                    # List changes/specs
-openspec validate <name>         # Validate change
-openspec status                  # Show progress
-openspec archive <name>          # Archive completed
-```
-### Claude Tasks Commands
-```bash
-/tasks save "description"        # Save current state
-/tasks list                      # List saved tasks
-/tasks resume <id>               # Resume a task
-/tasks delete <id>               # Delete a task
-```
-### Forge Commands
 ```bash
-/status                          # Check current state
-/research <feature>              # Research a feature
-/plan <feature>                  # Create implementation plan
-/dev                             # TDD development
-/check                           # Run all validations
-/ship                            # Create PR
-/review <pr>                     # Address PR feedback
-/merge <pr>                      # Merge PR
-/verify                          # Final doc check
+# Forge commands
+/status                    # Check current context
+/research <feature>        # Research + document
+/plan <feature>            # Create plan + branch
+/dev                       # TDD development
+/check                     # Validate everything
+/ship                      # Create PR
+/review <pr>               # Address feedback
+/merge <pr>                # Merge + cleanup
+/verify                    # Final docs check
+# Beads commands (optional)
+bd init                    # Initialize tracking
+bd ready                   # Find ready work
+bd create "title"          # Create issue
+bd update <id> --status X  # Update status
+bd sync                    # Sync with git
+# OpenSpec commands (optional)
+/opsx:new                  # Start change
+/opsx:ff                   # Generate all docs
+/opsx:apply                # Implement tasks
+/opsx:archive              # Complete change
 ```
-## Core Principles
-### TDD-First
-Every feature starts with tests:
-```
-RED    -> Write a failing test
-GREEN  -> Write minimal code to pass
-REFACTOR -> Clean up, commit
-REPEAT -> Next test case
-```
-### Research-First
-Before building, understand:
-1. **Codebase** - Existing patterns, affected modules
-2. **Best practices** - Web research, official docs
-3. **Security** - OWASP Top 10 analysis
-4. **Decisions** - Document WHY, not just WHAT
-### Security Built-In
-Every feature includes:
-- OWASP Top 10 analysis in research
-- Security test scenarios in TDD
-- Automated scans in `/check`
-- Security review in PR
-### Documentation Progressive
-Update docs at each stage:
-- `/research` -> Research document
-- `/plan` -> Beads issue, OpenSpec (if strategic)
-- `/ship` -> PR description
-- `/merge` -> PROGRESS.md, API docs
-- `/verify` -> Cross-check everything
-## Agent Compatibility
-Forge is designed for Claude Code's extensive features but adapts to all agents:
+---
-### Feature Availability by Agent
+## License
-| Feature | Claude Code | Cursor | Windsurf | Kilo | Others |
-|---------|-------------|--------|----------|------|--------|
-| **Slash Commands** | `/status` etc. | Via rules | `/status` etc. | `/status.md` | AGENTS.md |
-| **Skills (SKILL.md)** | Full | Full | Full | Full | Partial |
-| **Rules** | `.claude/rules/` | `.mdc` | `.windsurf/rules/` | `.kilocode/rules/` | AGENTS.md |
-| **Tasks Save/Resume** | `/tasks` | Memory | Memories | Memory Bank | Manual |
-| **Issue Tracking** | Beads | Beads | Beads | Memory Bank | Beads |
-| **Proposals** | OpenSpec | OpenSpec | OpenSpec | OpenSpec | OpenSpec |
+MIT © Harsha Nandak
-### How Forge Adapts
+---
-**Claude Code** (Full Support):
-```bash
-/status           # Native slash command
-/tasks save       # Built-in task persistence
-bd ready          # Beads integration
-```
+**Ready to start?**
-**Cursor/Windsurf** (Near-Full Support):
 ```bash
-# Read AGENTS.md instructions
-# Use Memories/Memory for persistence
-# Same Beads/OpenSpec workflow
-```
-**Other Agents** (AGENTS.md Fallback):
-```
-The agent reads AGENTS.md and follows the 9-stage workflow.
-Users describe what stage they're at: "I'm at the /dev stage"
-Agent follows the documented process.
-```
-### The Universal Principle
-Even without slash commands, the **workflow principles** work everywhere:
-1. **Check status before starting** - Review active work, git state
-2. **Research before building** - Document decisions
-3. **Plan formally** - Create tracking issue, branch
-4. **TDD development** - RED-GREEN-REFACTOR
-5. **Validate thoroughly** - Type/lint/test/security
-6. **Document in PR** - Link research, list tests
-7. **Address ALL feedback** - CI failures, reviews
-8. **Update docs before merge** - PROGRESS.md, API docs
-9. **Verify completeness** - Cross-check everything
-### Persistence Across Agents
-| Agent | How to Persist Context |
-|-------|------------------------|
-| **Claude Code** | `/tasks save`, Beads issues |
-| **Cursor** | Composer memory, Beads |
-| **Windsurf** | Cascade Memories, Beads |
-| **Kilo Code** | Memory Bank, Beads |
-| **Cline** | Memory Bank, Beads |
-| **Others** | Beads (git-backed, universal) |
-**Beads is the universal solution** - it works with ANY agent because it's git-backed.
-### Why This Architecture?
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    FORGE ARCHITECTURE                        │
-├─────────────────────────────────────────────────────────────┤
-│                                                              │
-│   AGENTS.md (Universal)                                      │
-│   ├── Works with EVERY agent                                 │
-│   ├── Plain markdown, no special features needed             │
-│   └── Contains full workflow documentation                   │
-│                                                              │
-│   Agent-Specific Enhancements (Optional)                     │
-│   ├── .claude/commands/  -> Native slash commands            │
-│   ├── .cursor/rules/     -> Cursor MDC rules                 │
-│   ├── .windsurf/workflows/ -> Windsurf workflows             │
-│   └── etc.                                                   │
-│                                                              │
-│   External Tools (Universal)                                 │
-│   ├── Beads   -> Issue tracking (git-backed)                 │
-│   ├── OpenSpec -> Architectural proposals                    │
-│   └── GitHub CLI -> PR workflow                              │
-│                                                              │
-└─────────────────────────────────────────────────────────────┘
+npm install forge-workflow
+npx forge setup
+/status
 ```
-The workflow **degrades gracefully**:
-- Full features in Claude Code
-- Most features in Cursor/Windsurf/Kilo
-- Core workflow in ANY agent via AGENTS.md
-## License
-MIT
-## Contributing
-Contributions welcome! Please read `docs/WORKFLOW.md` before submitting PRs.
----
-**Start with:** `npm install forge-workflow && npx forge setup`
-**Then:** `/status` to see where to begin!
+Then open [QUICKSTART.md](QUICKSTART.md) and ship your first feature! 🚀