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

# Issue commands (via Forge)
bd init                    # Initialize Beads tracking
forge ready                # Find ready work
forge create "title"       # Create issue
forge update <id> --status X  # Update status
forge sync                 # Sync Beads state

For advanced Beads operations that Forge does not wrap yet, use bd directly for
bd comments, bd dep, and bd dolt.

Forge is the preferred command surface for routine workflows, but Beads (bd)
remains the underlying source of truth for issue state and IDs.

---

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! 🚀