Concepts

How Forge DevKit thinks, why it works this way, and what makes it different from prompt libraries.

Meta-Tool Architecture

Forge is not a prompt library. It is a meta-tool - a tool that generates tools. When you run /forge:setup, Forge analyzes your project and generates project-specific artifacts: dev-skills, quality patterns, pipeline configurations, and guardrails. These artifacts live in your project's .claude/ directory and work autonomously.

◆

Disposable by design: After setup, you can uninstall Forge entirely. The generated artifacts continue to work - they are self-contained files your AI reads on session start. Forge is the generator, not the runtime.

How it works

Detection. Forge scans your project: stack, frameworks, architecture layers, conventions, file structure, dependencies. No configuration files needed.

Generation. Based on detection results, Forge generates artifacts tailored to your project: dev-skills with your conventions, quality patterns for your stack, pipeline phases for your workflow.

Autonomy. Generated artifacts are loaded by your AI automatically on every session start. They contain your project's architecture, patterns, and rules - so the AI never forgets.

Detection Over Configuration

Forge contains zero hardcoded project knowledge. It does not ship with NestJS templates, React patterns, or Django conventions. Instead, it detects what your project uses and generates artifacts from what it finds.

The 7-gate setup wizard examines your actual codebase: package.json, directory structure, import patterns, Docker configs, CI pipelines, database migrations. It builds a model of your architecture - not from templates, but from evidence.

What Forge detects

✓ Stack and frameworks
✓ Architecture layers and boundaries
✓ Naming conventions and code style
✓ Test frameworks and patterns
✓ Docker, CI/CD, and infrastructure
✓ Database and ORM setup
✓ Auth, events, and AI/LLM patterns

Why detection matters

✓ Works with any stack combination
✓ No config files to maintain
✓ Adapts to your project, not the other way around
✓ Captures conventions templates miss
✓ Reconfigure anytime as your project evolves

Core + Adapters

Forge uses a core + adapter architecture. forge-core is the foundation - it handles setup, detection, artifact generation, and the development pipeline. Every other module is an adapter that extends the core.

Adapters are independent plugins that connect through shared state in .claude/forge/. Each adapter reads artifacts from others it depends on (discovery reads nothing, marketing reads discovery, copy reads marketing) - but all dependencies are optional. Every adapter works standalone; it just gets smarter with context from neighbors.

Ecosystem flow

discovery → marketing → product → /dev pipeline ↓ copy, seo, analytics ↓ onboarding, growth, ab

◆

Install what you need. Starter plan gives you the core pipeline (forge-core + forge-worktree). Pro adds product design, testing, task tracking, and prompt management. Complete unlocks 8 advisory modules that surround the pipeline with strategy: from discovery to A/B testing.

The Development Pipeline

When you type /dev, Forge activates a multi-phase pipeline generated specifically for your project. Each phase has clear boundaries, quality checks, and guardrails that prevent the AI from cutting corners.

Pipeline phases

Phase 0

Understand. Read the task, load context from tracker and product artifacts, plan the approach.

Phase 1

Plan. Break task into steps, identify affected files and layers, validate against architecture.

Phase 2

Implement. Write code following detected conventions, layer boundaries, and naming patterns.

Phase 3

Test. Generate tests from acceptance criteria (not AI guesswork), run quality gates.

Phase 4

Review. Self-review against 50+ quality patterns, check for rationalization, verify completeness.

Each phase includes rationalization detectors - 15 patterns that catch when AI tries to skip steps, simplify requirements, or cut corners. These are calibrated to your project's complexity level, so they don't slow down simple tasks but catch shortcuts on complex ones.

Quality Patterns

After detecting your project's capabilities (UI, API, database, Docker, auth, events, AI), Forge generates quality patterns scoped to what you actually have. A backend API project gets different patterns than a full-stack app with a React frontend.

UI Patterns

Component boundaries, state management, accessibility, responsive design, performance budgets

API Patterns

Error handling, validation, authentication guards, rate limiting, response contracts

Infrastructure Patterns

Docker configuration, CI/CD safety, environment isolation, migration strategies

Shared Patterns

Naming conventions, layer boundaries, dependency rules, code organization, test structure

Upgrade & Evolution

Forge tracks ownership of every generated file with version headers. When you upgrade a plugin, Forge knows which files it generated (safe to update) and which you modified (preserved). Run /forge:setup upgrade to check for updates and apply them safely.

Your project evolves, and Forge evolves with it. Changed your testing framework? Restructured your layers? Run /forge:setup reconfigure to re-detect and regenerate artifacts. The wizard saves progress after each gate, so interruptions are safe.

Customizing Your Pipeline

Forge generates a pipeline tailored to your project - but you are not locked into it. You can add custom steps, inject your own logic, create project-specific skills, and integrate them into the ecosystem. Everything you add is tracked and survives upgrades.

Adding Steps to the Pipeline

The development pipeline is built from a step catalog - a structured registry of all phases and steps your AI follows. You can add custom steps to any phase using /forge:patch.

Example: adding a custom linting step

# Run the patch command

$ /forge:patch

# Select "step-catalog.md" as target

# Forge creates:

step-catalog.md ← new row with [patch:patch.2.1] tag

.claude/forge/patches/patch.2.1.md ← step body

.claude/forge/patches/registry.yaml ← tracked for upgrades

Patched steps are tagged with [patch:{id}] in the catalog. When you upgrade Forge, the catalog is regenerated from the latest template - then your patches are re-applied automatically from the registry. Your custom logic is never lost.

◆

Three patchable artifact types: Managed files (full forge-owned), augmented files (user-owned with forge sections), and catalog files (step tables). Each type has its own scope rules to prevent accidental overwrites.

Creating Your Own Skills

Beyond patching steps, you can create entirely new skills that live alongside Forge's generated ones. A skill is just a SKILL.md file in .claude/skills/ with a name and description in frontmatter.

Skill file structure

.claude/skills/ forge-dev-context/ # generated by Forge forge-dev-implement/ # generated by Forge my-deploy-check/ # your custom skill SKILL.md references/ deploy-checklist.md

Your skill's SKILL.md needs frontmatter with name and description - the description is what the AI uses to decide when to activate the skill. Write it clearly: "Use this skill when deploying to staging or production" works better than "deployment helper".

✓

Coexistence by design. Your custom skills and Forge-generated skills share the same .claude/skills/ directory. Forge tracks its own files with managed headers and never touches files it did not create. When you run an upgrade, your skills are left untouched.

Augmenting Existing Skills

If you already have dev-skills in your project before installing Forge, the setup wizard detects them and runs a gap analysis. It compares your skill against 13 core features (phased pipeline, resume protocol, quality patterns, etc.) and recommends one of three modes:

Keep

Your skill already covers 80%+ of Forge features. No changes needed.

Augment

Your skill is good but missing specific features. Forge injects them as marked sections - your content stays untouched.

Replace

Coverage is low. Forge generates fresh skills from scratch, keeping your original as backup.

Augmented sections are wrapped in markers like . During upgrades, only the content inside markers is refreshed - everything outside remains yours.

How Hub Discovers Your Skills

The Forge Hub (/forge:hub) is an intent router that classifies what you want and finds the right skill to handle it. It starts with a bootstrap check, then discovers skills at two levels:

✓

Works with any project state. Run /forge:hub on an empty directory - it detects the situation and offers /forge:init to scaffold a new project. Run it on an existing project without Forge - it automatically launches /forge:setup to configure the pipeline. Run it on a configured project - it routes directly to the right skill. No prerequisites to remember.

Hub discovery layers

Bootstrap. Hub checks if Forge is configured. No config? It runs setup automatically. Empty project? It offers init. You never hit a dead end.

Installed adapters. Hub reads .claude/forge/core/config.yaml to know which Forge modules are active. This drives the dependency graph walk and prerequisite resolution.

Project skills. Your AI automatically loads all skills from .claude/skills/ on session start - both Forge-generated and your custom ones. Hub routes to whichever skill matches the intent, whether it was created by Forge or by you.

When you say /forge:hub check deploy readiness and you have a custom my-deploy-check skill, the AI sees it in the skill list and can route to it. No extra configuration needed - just the SKILL.md description is enough for the AI to match intent to skill.

Missing adapters? Hub offers to install them

When Hub walks the dependency graph and finds a needed module is not installed, it does not silently skip it. Instead, it classifies the impact and offers a choice:

Required

The target adapter is missing. Hub stops and offers to install it right now. After setup completes, the chain continues.

Recommended

An upstream module would significantly improve output quality. Hub explains the value and offers install. You can skip if you prefer.

Optional

A nice-to-have enrichment. Hub skips it silently and logs the recommendation in the execution report.

◆

New adapters need a pipeline refresh. If you install a new Forge adapter (like forge-analytics), run /forge:setup upgrade so the step catalog gets refreshed with the new module's steps. Hub itself needs no upgrade - it reads config.yaml dynamically. But the dev pipeline's step catalog is a generated artifact and needs regeneration to include steps from the new adapter.

Pipeline Config Overrides

For advanced control, you can override pipeline behavior without touching generated files. The pipeline config at .claude/forge/core/pipeline-config.yaml lets you pin or skip adapter manifests, set execution mode defaults, and configure cost controls.

Example: pipeline-config.yaml

# Skip advisory modules for fast iteration skip_manifests: - forge-seo-manifest - forge-analytics-manifest # Pin execution mode execution_mode: balanced # Cost controls max_subagents: 3

This file is user-owned (no managed header) - Forge never overwrites it. Changes take effect on the next /dev run.

Ready to see it in action?

Get started in 5 minutes → All 15 modules