ForgeCraft

Production engineering standards for any AI coding assistant.

AI coding assistants work better with clear engineering standards. Most start with a generic instruction file — ForgeCraft replaces that with production-grade standards: SOLID principles, testing pyramids, architecture patterns, CI/CD pipelines, domain-specific rules, and quality-gate hooks — all composed from 112 curated template blocks matched to your actual stack.

Supports: Claude (CLAUDE.md) · Cursor (.cursor/rules/) · GitHub Copilot (.github/copilot-instructions.md) · Windsurf (.windsurfrules) · Cline (.clinerules) · Aider (CONVENTIONS.md)

claude mcp add forgecraft -- npx -y forgecraft-mcp

Then tell Claude:

"Set up this project for production"

Done. Your AI assistant now has tailored instruction files with SOLID principles, testing standards, architecture patterns, CI/CD guidance, and quality-gate hooks — all matched to your stack.

claude init vs ForgeCraft

How It Works

You: "Set up this project for production"

Claude calls setup_project → scans your code → detects [API] + [WEB-REACT]
                           → creates forgecraft.yaml
                           → generates instruction files for your AI assistant(s)
                           → adds quality-gate hooks
                           → done

ForgeCraft is an MCP server — it gives Claude 14 specialized tools. Claude picks the right ones automatically. You just describe what you want in plain English.

Already ran claude init? ForgeCraft's generate_instructions can merge with your existing CLAUDE.md (merge_with_existing: true), keeping your custom sections while adding production standards.

Install

One line. Takes 10 seconds.

claude mcp add forgecraft -- npx -y forgecraft-mcp

Restart Claude Code. That's it.

{
  "mcpServers": {
    "forgecraft": {
      "command": "npx",
      "args": ["-y", "forgecraft-mcp"]
    }
  }
}

What You Get

After setup_project, your project has:

your-project/
├── forgecraft.yaml        ← Your config (tags, tier, customizations)
├── CLAUDE.md              ← Engineering standards (Claude)
├── .cursor/rules/         ← Engineering standards (Cursor)
├── .github/copilot-instructions.md  ← Engineering standards (Copilot)
├── Status.md              ← Session continuity tracker
├── .claude/hooks/         ← Pre-commit quality gates
├── docs/
│   ├── PRD.md             ← Requirements skeleton
│   └── TechSpec.md        ← Architecture + NFR sections
└── src/shared/            ← Config, errors, logger starters

The Instruction Files

This is the core value. Assembled from curated blocks covering:

• SOLID principles — concrete rules, not platitudes
• Hexagonal architecture — ports, adapters, DTOs, layer boundaries
• Testing pyramid — unit/integration/E2E targets, test doubles taxonomy
• Clean code — CQS, guard clauses, immutability, pure functions
• CI/CD & deployment — pipeline stages, environments, preview deploys
• Domain patterns — DDD, CQRS, event sourcing (when your project needs it)
• 12-Factor ops — config, statelessness, disposability, logging

Every block is sourced from established engineering literature (Martin, Evans, Wiggins) and adapted for AI-assisted development.

18 Tags — Pick What Fits

Tags are domain classifiers. ForgeCraft auto-detects them from your code, or you choose manually. Combine freely — blocks merge without conflicts.

Content Tiers

Not every project needs DDD on day one.

Set in forgecraft.yaml:

projectName: my-api
tags: [UNIVERSAL, API]
tier: recommended

All 14 Tools

Configuration

Fine-tune what Claude sees

# forgecraft.yaml
projectName: my-api
tags: [UNIVERSAL, API, FINTECH]
tier: recommended
outputTargets: [claude, cursor, copilot]  # Generate for multiple assistants

exclude:
  - cqrs-event-patterns    # Don't need this yet

variables:
  coverage_minimum: 90      # Override defaults
  max_file_length: 400

Community template packs

templateDirs:
  - ./my-company-standards
  - node_modules/@my-org/forgecraft-flutter/templates

Keeping Standards Fresh

Audit (run anytime, or in CI)

Score: 72/100  Grade: C

✅ Instruction files exist
✅ Hooks installed (3/3)
✅ Test script configured
🔴 hardcoded_url: src/auth/service.ts
🔴 status_md_current: not updated in 12 days
🟡 lock_file: not committed

Refresh (project scope changed?)

Tell Claude "refresh this project" — it re-scans, suggests new tags, shows before/after impact, and updates everything on approval.

Contributing

Templates are YAML, not code. You can add patterns without writing TypeScript.

templates/your-tag/
├── instructions.yaml   # Instruction file blocks (with tier metadata)
├── structure.yaml      # Folder structure
├── nfr.yaml            # Non-functional requirements
├── hooks.yaml          # Quality gate scripts
└── review.yaml         # Code review checklists

PRs welcome. See templates/universal/ for the format.

Development

git clone https://github.com/jghiringhelli/forgecraft-mcp.git
cd forgecraft-mcp
npm install
npm run build
npm test   # 111 tests, 9 suites

License

MIT