Forge

Ship features with confidence using a 7-stage TDD-first workflow for AI coding agents.

/plan → /dev → /validate → /ship → /review → /premerge → /verify

✅ TDD-First: Write tests before code ✅ Design-First: One-question-at-a-time Q&A captures intent upfront ✅ Multi-Agent: Universal AGENTS.md works with 8 agents

Quick Example

Adding a login button with Forge:

/plan login-button        # Design Q&A → research → branch + task list
/dev                      # TDD: RED → GREEN → REFACTOR cycles
/validate                 # Type check + lint + tests + security scan
/ship                     # Create PR with full documentation

Result: Feature shipped with tests, security validated, fully documented.

Without Forge (chaotic):

• Code first, tests later (or never)
• No research or planning
• Security issues found in production
• Documentation forgotten

With Forge (systematic):

• Tests written BEFORE code (TDD)
• Research-backed decisions
• OWASP Top 10 analysis in every /plan
• Documentation at every stage

→ See complete walkthrough in QUICKSTART.md

Installation

# Step 1: Install the package (as dev dependency)
bun add -D forge-workflow

# Step 2: Setup for your AI agent
bunx forge setup

That's it! Forge will:

• Create AGENTS.md (universal instructions)
• Setup agent-specific files (Claude, Cursor, etc.)
• Create docs/ folder with guides

Prerequisites: Node.js, Git, GitHub account Optional tools: Beads (issue tracking)

Setup Flags

| Flag | Description | |------|-------------| | --agents=<list> | Comma-separated agents to set up (e.g., --agents=claude,cursor) | | --all | Set up all supported agents | | --dry-run | Preview what setup would do without writing files | | --non-interactive | Skip all prompts (use defaults). Auto-enabled when CI=true | | --symlink | Create CLAUDE.md as a symlink to AGENTS.md instead of a copy | | --sync | Enable Beads GitHub sync (scaffolds workflow + PAT) | | --verbose | Show file-by-file detail instead of summary | | --force | Overwrite existing files even if content matches |

→ Detailed setup guide for all agents

The 7 Stages

| Stage | Command | Purpose | |-------|---------|---------| | utility | /status | Ranked issue dashboard with conflict detection | | 1. Plan | /plan | Design Q&A → research → branch + task list | | 2. Dev | /dev | Subagent TDD per task (spec + quality review) | | 3. Validate | /validate | Validate: types, lint, tests, security | | 4. Ship | /ship | Create PR with documentation | | 5. Review | /review | Address ALL PR feedback (Greptile, reviewers, CI/CD) | | 6. Premerge | /premerge | Complete docs on feature branch, hand off PR | | 7. Verify | /verify | Post-merge health check (CI on main) |

Full workflow guide: AGENTS.md

Supported AI Agents

Works with 8 AI coding agents via universal AGENTS.md:

Tier 1 (Primary Support)

| Agent | Features | Setup Time | |-------|----------|------------| | Claude Code | Custom slash commands, .claude/ directory | 30 seconds | | GitHub Copilot | Enterprise support, .github/copilot-instructions.md | 30 seconds | | Kilo Code | Auto failure recovery, .kilo.md | 30 seconds | | Cursor | Native modes (Plan/Ask/Debug), .cursor/rules/ | 30 seconds | | Codex CLI | OpenAI terminal agent, AGENTS.md | 30 seconds |

Tier 2 (Optional Support)

| Agent | Features | Setup Time | |-------|----------|------------| | OpenCode | Flexible, opencode.json | 30 seconds | | Goose | Model flexibility, open-source | 30 seconds |

Quick setup (auto-detects agents):

bunx forge setup

Setup for specific agent:

bunx forge setup --agent=copilot     # GitHub Copilot
bunx forge setup --agent=cursor      # Cursor IDE
bunx forge setup --agent=kilo        # Kilo Code
bunx forge setup --agent=codex       # Codex CLI

Setup for all Tier 1 agents:

bunx forge setup --all

→ Agent-specific setup instructions

What Makes Forge Different

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

No feature ships without tests. Period.

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

Saves hours of debugging and refactoring later.

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

Switch agents anytime without changing your workflow.

4. Built-in TDD Enforcement

Git hooks automatically enforce TDD practices:

• Pre-commit: Blocks source commits without tests
• Pre-push: Runs full test suite before push
• Interactive: Guided recovery when violations occur
• CI/CD aware: Auto-aborts in non-interactive environments

# Validation CLI
forge-preflight status    # Check project prerequisites
forge-preflight dev       # Validate before /dev stage
forge-preflight ship      # Validate before /ship stage

5. Smart Tool Recommendations

Curated plugin catalog across 7 workflow stages — plan, dev, validate, ship, review, and more:

• Auto-detection: Scans your project for frameworks, databases, auth, payments, and more
• Budget modes: free, open-source, startup, professional, custom
• Portability-first: MCPs included only when they add clear value over CLI alternatives
• Free alternatives: Every paid tool shows free alternatives

bunx forge recommend                  # Recommendations for your project
bunx forge recommend --budget free    # Only free tools

→ Validation docs | Plugin docs

6. Enhanced Onboarding

Smart setup that adapts to your project:

Intelligent File Merging

• Preserves your existing AGENTS.md content
• Adds Forge workflow without overwriting
• Three options: smart merge, keep, or replace

bunx forge setup --merge=smart    # Intelligent merge

Auto-Detection

• Detects framework (Next.js, React, Vue, Express)
• Detects language (TypeScript, JavaScript)
• Analyzes git stats and CI/CD setup
• Infers project stage (new, active, stable)
• Saves to .forge/context.json

Workflow Profiles (planned — not yet wired into setup)

• Will adapt workflow based on work type (3-8 stages):
  • critical: Full 8-stage workflow (auth, payments, security-sensitive)
  • standard: 7-stage workflow (typical features)
  • refactor: Behavior-preserving 5-stage workflow
  • simple: Streamlined 4-stage workflow
  • hotfix: Minimal 3-stage workflow (production fixes)
  • docs: Minimal 3-stage workflow (documentation/config)

bunx forge setup --type=critical    # Set workflow manually

Context Interview (optional)

bunx forge setup --interview    # Gather project context

→ Enhanced onboarding guide

7. Automated Quality Gates 🆕

Multi-layer quality enforcement before merge:

Greptile AI Code Review

• AI-powered review on every PR
• Catches bugs, security issues, performance problems
• Detailed inline feedback with fix suggestions
• Automatic re-review after changes

# Branch protection requires Greptile review to pass
# Typically completes in 1-2 minutes

GitHub Actions Workflows

• Greptile Quality Gate: Enforces minimum score (≥4/5)
• ESLint checks: Code quality validation
• Test suite: All tests must pass

Git Hooks (Lefthook)

• Pre-commit: TDD enforcement (tests required)
• Pre-push: Full test suite + lint checks
• Branch protection: Blocks direct push to main/master

→ Greptile setup guide

The Toolchain

Forge integrates with powerful tools:

┌──────────────────────────────────────────────┐
│              FORGE TOOLCHAIN                 │
├──────────────────────────────────────────────┤
│                                              │
│  ┌──────────┐                  ┌──────────┐  │
│  │  BEADS   │                  │  GITHUB  │  │
│  │  Issue   │                  │    PR    │  │
│  │ Tracking │                  │ Workflow │  │
│  └──────────┘                  └──────────┘  │
│       │                              │       │
│       └──────────────────────────────┘       │
│                      │                       │
│                ┌─────▼─────┐                 │
│                │   FORGE   │                 │
│                │ 7-Stage   │                 │
│                │ Workflow  │                 │
│                └───────────┘                 │
│                                              │
└──────────────────────────────────────────────┘

All tools are optional - Forge works standalone.

Beads (optional): Git-backed issue tracking that survives context clearing

bun add -g @beads/bd && bd init

GitHub CLI (recommended): Required for PR workflow

gh auth login

→ Complete toolchain guide

Real-World Examples

Example 1: Simple Feature (20 minutes)

Task: Add a health check endpoint

/plan health-check-endpoint      # Design Q&A → research → branch + task list
/dev                             # 8 min: TDD implementation
/validate                           # 2 min: All validations pass
/ship                            # 2 min: PR created
# → Greptile AI review completes (~2 min)
/review                          # 3 min: Address Greptile feedback
/premerge                        # 2 min: Complete docs, hand off PR

Example 2: Bug Fix with Security (30 minutes)

Task: Fix SQL injection vulnerability

/plan sql-injection-fix          # Design Q&A → OWASP research → branch
/dev                             # 8 min: Fix + tests
/validate                           # 3 min: Security scan
/ship                            # 2 min: PR with security notes
# → Greptile validates security fix (~2 min)
/review                          # 5 min: Address security feedback
/premerge                        # 3 min: Complete docs, hand off PR

Example 3: Architecture Change (2-3 days)

Task: Add authentication system

/plan user-authentication        # Design Q&A → deep research → branch
/dev                             # 1-2 days: TDD implementation
/validate                           # 30 min: Full validation
/ship                            # 15 min: PR with docs
/review                          # Varies: Address feedback
/premerge                        # 15 min: Complete docs, hand off PR
/verify                          # 15 min: Post-merge health check

→ More examples in docs/EXAMPLES.md

Core Principles

TDD-First: Tests before code, always Design-First: One-question-at-a-time Q&A captures intent before research Security Built-In: OWASP Top 10 for every feature Documentation Progressive: Update at each stage Multi-Session: Work persists across sessions

→ Read the philosophy in AGENTS.md

Next Steps

📚 New to Forge? → QUICKSTART.md - Your first feature in 5 minutes

📖 Learn the workflow → AGENTS.md - Complete guide with examples

🛠️ Setup the toolchain → docs/TOOLCHAIN.md - Beads, GitHub CLI

🎯 See real examples → docs/EXAMPLES.md - Real-world use cases

💬 Have questions? → GitHub Discussions

🐛 Found a bug? → GitHub Issues

Quick Reference

# Forge commands
/status                    # Check current context
/plan <feature>            # Design Q&A → research → branch + task list
/dev                       # TDD development
/validate                     # Validate everything
/ship                      # Create PR
/review <pr>               # Address feedback
/premerge <pr>             # Complete docs, hand off PR
/verify                    # Post-merge health 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

License

MIT © Harsha Nandak

Ready to start?

bun add -D forge-workflow
bunx forge setup
/status

Then open QUICKSTART.md and ship your first feature! 🚀