Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (forge-workflow) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

Ready to start?

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

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