DevForge

Universal, AI-first project scaffolding CLI. Describe what you're building, get the right stack recommended, and ship with Claude Code infrastructure pre-configured.

Quick Start

# New project — guided (for beginners)
npx forgedev new my-app

# New project — shorthand
npx forgedev my-app

# Add dev guardrails to existing project
npx forgedev init

# Diagnose and optimize existing project
npx forgedev doctor

# Check for updates
npx forgedev update

Four Modes, Four Audiences

1. Guided Mode (beginners & non-developers)

Describe what you want in plain English. DevForge picks the stack.

$ npx forgedev new my-app

  🔨 DevForge — Let's build something.

? How would you like to start?
  💬 Describe what you want to build (recommended for beginners)
  ⚡ I know my stack — let me pick (for developers)

> Describe

Tell me about what you want to build:
> I want an app where restaurants manage their menu and customers order food

  Got it! Here's what I'll set up for you:

  What you'll get:
  ├── A website where you can:
  │   • Manage menu
  │   • Manage orders
  │
  ├── User accounts (with different roles like admin and user)
  ├── Payment processing for orders or subscriptions
  ├── Search and filtering
  ├── A database to store all your data
  │
  └── Developer tools:
      • Code quality checks (catches errors automatically)
      • Guided workflows (type /workflows anytime you're stuck)
      • Testing templates

? Sound right? Yes — create it!

Zero technical jargon. DevForge makes all the decisions. After scaffolding, generates docs/getting-started.md with a beginner-friendly walkthrough.

2. Developer Mode (developers who know their stack)

$ npx forgedev new my-app

? How would you like to start?
  ⚡ I know my stack — let me pick

? What are you building? Full-stack app
? Backend language? Python (polyglot)
? Need authentication? Yes
? Deployment target? Docker

  Recommended stack:
  Frontend: nextjs + typescript + tailwind + shadcn
  Backend:  fastapi + python + sqlalchemy
  Database: postgresql (both)
  Auth:     both
  Testing:  vitest + playwright + pytest
  Deploy:   docker
  Claude:   CLAUDE.md + hooks + skills + agents + commands

? Proceed with this stack? Yes

✓ Done! Your project is ready.

3. Init Mode (add guardrails to existing projects)

$ cd my-existing-project
$ npx forgedev init

  🔨 DevForge — Adding dev guardrails

  Scanning...

  Detected: nextjs (typescript) + fastapi (python) + postgresql (prisma) + vitest + playwright + pytest

  Installing:
  ✓ CLAUDE.md — project context + rules
  ✓ .claude/hooks/ — auto-lint, quality gate, file protection
  ✓ .claude/agents/ — code quality, security, spec validator
  ✓ .claude/commands/ — workflows, status, next, done, audit, pre-pr
  ✓ .claude/skills/ — framework-specific knowledge
  ✓ docs/uat/ — acceptance test templates

  Done. Your project is now configured for Claude Code.

  Next steps:
    1. Open Claude Code in this directory: claude
    2. Type /workflows to see available workflows

Zero questions. Scans, detects, installs.

4. Doctor Mode (diagnose & optimize existing projects)

$ npx forgedev doctor

  🔨 DevForge Doctor — Project Health Check

  Scanning...

  📊 Project Vitals:
  Frontend:  nextjs (typescript)
  Backend:   fastapi (python)
  Database:  postgresql (sqlalchemy)
  Testing:   vitest + playwright + pytest

  Health Issues Found:

  🔴 CRITICAL
    1. CLAUDE.md is 647 lines (recommended limit: 150)
       → Instructions are being dropped
    2. 4 endpoints have no authentication
       → Security vulnerability

  🟡 WARNING
    3. No health check endpoint
    4. No UAT scenarios
    5. 3 bare except: blocks

  ? What would you like to do?
    🚑 Fix critical issues (guided, one at a time)
    📋 Generate a full report (save to docs/doctor-report.md)
    ⚡ Auto-fix what's safe to auto-fix
    📖 Just show me what to do (generates prompts for Claude Code)

Doctor diagnoses problems and generates the exact Claude Code prompt to fix each one.

Supported Stacks (V1)

| Selection | Stack | |---|---| | Web app / Full-stack + TypeScript | Next.js 15 + Prisma + PostgreSQL + NextAuth + Vitest + Playwright | | API service + Python | FastAPI + SQLAlchemy 2.0 + PostgreSQL + Alembic + Pytest | | Full-stack + TS + Python | Next.js frontend + FastAPI backend (polyglot monorepo) | | AI/ML service | Polyglot full-stack with AI integration flag |

What Gets Generated

Every project includes:

• Project scaffold with working code, configs, and dependencies
• Health check endpoints (/health, /healthz)
• Graceful shutdown handlers
• Database connection retry with exponential backoff
• Structured error responses (never leaks stack traces)

With Claude Code infrastructure enabled (default):

• CLAUDE.md tailored to your stack (with pitfalls and agents quick-reference)
• Hooks — cross-platform Node.js .mjs hooks (auto-lint on edit, quality gate, protected file guard)
• 17 Agents — verification, development, review, and orchestration (see below)
• 20 Commands — daily workflow, verification, release, development, session management
• 8 Skills — framework-specific + universal knowledge
• UAT templates — scenario packs and CSV checklists
• Prompt library — the complete development prompt library

Agents (18)

Every scaffolded project gets these agents in .claude/agents/:

| Agent | Role | Access | |-------|------|--------| | architect | System design, data models, API contracts | Read-only | | build-error-resolver | Fix build/lint/type errors with minimal changes | Write | | chief-of-staff | Orchestrate multiple agents for complex tasks | Write | | code-quality-reviewer | Code quality review | Read-only | | database-reviewer | Query optimization, schema review, N+1 detection | Read-only | | doc-updater | Keep docs in sync with code changes | Write | | docs-lookup | Search framework docs for answers | Read-only | | e2e-runner | Generate and run Playwright E2E tests | Write | | harness-optimizer | Audit Claude Code setup, suggest optimizations | Read-only | | loop-operator | Autonomous improvement loops with stop conditions | Write | | planner | Create implementation plans before coding | Read-only | | product-strategist | Research competitors, evaluate maturity, recommend improvements | Read-only | | production-readiness | Production deployment readiness review | Read-only | | refactor-cleaner | Dead code removal, duplicate elimination | Write | | security-reviewer | Security audit | Read-only | | spec-validator | Validate implementation matches specification | Read-only | | tdd-guide | Enforce RED-GREEN-REFACTOR TDD cycle | Write | | uat-validator | QA validation of UAT scenarios | Read-only |

Skills (8)

| Skill | Scope | |-------|-------| | nextjs | Next.js 15 App Router patterns | | fastapi | FastAPI + SQLAlchemy 2.0 + Pydantic v2 | | playwright | Playwright E2E testing | | security-web | Web application security | | security-api | API security | | ai-prompts | AI/LLM integration patterns | | git-workflow | Git branching, commits, PR workflow (universal) | | testing-patterns | Test pyramid, AAA pattern, mocking (universal) |

Development

npm install
npm test                           # run unit tests
node bin/devforge.js test-output   # manual smoke test (guided + developer)
node bin/devforge.js init          # test init mode (from any project dir)
node bin/devforge.js doctor        # test doctor mode (from any project dir)
node bin/devforge.js update        # check for updates

Project Structure

devforge/
├── bin/devforge.js              # CLI entry point
├── src/
│   ├── cli.js                   # Command router (new, init, doctor, update)
│   ├── index.js                 # New project orchestrator (guided + developer)
│   ├── guided.js                # Guided mode (description → stack)
│   ├── prompts.js               # Interactive prompts (Inquirer.js)
│   ├── recommender.js           # Service type → stack recommendation
│   ├── composer.js              # Template composition engine
│   ├── claude-configurator.js   # Generates .claude/ infrastructure
│   ├── uat-generator.js         # Generates UAT templates
│   ├── scanner.js               # Project scanner (for init + doctor)
│   ├── init-mode.js             # Init mode orchestrator
│   ├── doctor.js                # Doctor mode orchestrator
│   ├── doctor-checks.js         # Diagnostic check functions
│   ├── doctor-prompts.js        # Fix prompt generators
│   ├── update-check.js          # npm registry version check
│   ├── update.js                # Update command handler
│   └── utils.js                 # File ops, logging, colors
├── templates/                   # Scaffold templates by category
│   ├── base/                    # Every project gets this
│   ├── frontend/nextjs/         # Next.js App Router
│   ├── backend/fastapi/         # FastAPI + SQLAlchemy
│   ├── database/                # Prisma, SQLAlchemy
│   ├── auth/                    # NextAuth, JWT
│   ├── testing/                 # Vitest, Playwright, Pytest
│   ├── infra/                   # Docker Compose, GitHub Actions
│   └── claude-code/             # Hooks, CLAUDE.md, skills, agents, commands
├── tests/                       # Vitest tests
└── docs/                        # Reference documentation

Claude Code Commands (20)

After running npx forgedev init, these slash commands are available inside Claude Code:

Daily Workflow:

| Command | What It Does | |---------|-------------| | /workflows | Lists all available workflows | | /status | Project dashboard — tests, branch, changes | | /next | Figures out your next task | | /done | Verifies task completion |

Verification:

| Command | What It Does | |---------|-------------| | /verify-all | Runs lint, type check, tests, then launches reviewers | | /full-audit | Runs every audit and review agent in a single pass | | /audit-spec | Validates implementation against a spec/PRD | | /audit-wiring | Finds dead or unwired features | | /audit-security | Runs a security audit | | /code-review | Reviews uncommitted changes for security and quality |

Release:

| Command | What It Does | |---------|-------------| | /pre-pr | Runs the complete pre-PR checklist | | /run-uat | Executes UAT scenarios |

Development:

| Command | What It Does | |---------|-------------| | /plan | Invoke planner agent for implementation planning | | /build-fix | Incrementally fix build/lint/type errors | | /tdd | Enforce test-driven development cycle | | /generate-prd | Generates a PRD with Mermaid diagrams | | /generate-uat | Generates UAT scenarios from codebase | | /optimize-claude-md | Proposes splitting an oversized CLAUDE.md |

Session:

| Command | What It Does | |---------|-------------| | /save-session | Save work context for later resumption | | /resume-session | Load saved session and continue where you left off |

Install

# Use directly (no install needed)
npx forgedev new my-app

# Or install globally
npm install -g forgedev

Package name on npm: forgedev

Roadmap

• [ ] Go + Gin/Chi backend
• [ ] Rust + Axum backend
• [ ] React + Vite SPA (frontend-only)
• [ ] React Native / Expo mobile
• [ ] Plugin ecosystem for community templates

License

MIT