boilerforge

Architecture governance wedge for AI-built codebases — doctor-first health checks and guardrails for production teams.

Boilerforge is now doctor-first. Instead of starting from a boilerplate registry, you start by checking architecture quality:

boilerforge doctor .

It scores your project, detects stack metadata, validates governance guardrails, and gives actionable recommendations.

Quickstart

npx -y @cometforge/boilerforge@latest doctor .

CI gate:

boilerforge doctor . --ci --min-score 70

Badge snippet:

boilerforge doctor . --badge

Example output:

![Boilerforge Score](https://img.shields.io/badge/boilerforge-78%2F100-yellow)

Related MCP server: trazabilidad-mcp

Commands

boilerforge doctor [path]

Architecture health report with weighted score (/100).

Flags:

• --json output machine-readable JSON

• --ci fail with non-zero exit if below threshold

• --min-score <number> threshold for --ci (default 70)

• --badge print markdown badge snippet + score

boilerforge analyze [path]

Detect stack metadata:

• language/runtime

• framework

• package manager

• baseline project metadata

boilerforge validate [path]

Evaluate architecture guardrails and return:

• pass/fail

• score

• categorized issues (critical, warning, info)

• recommendations

boilerforge extract [path] [--name <template-name>]

Extract current project into local template registry:

• writes .boilerforge-template.yaml in source project

• creates template under ~/.boilerforge/registry/<template-name>/

• copies sane files only (excludes .git, node_modules, dist, build artifacts, env secrets)

boilerforge create <template-name> [target-path]

Scaffold a project from local registry template and write lockfile (boilerforge.lock.json).

boilerforge upgrade [path]

Upgrade project based on lockfile + local template version:

• compares locked template version vs latest local registry

• applies migration hooks in order when present (writeFile, appendFile, deleteFile, copyFromTemplate, patchJSON)

• writes updated lockfile

Doctor Rule Engine (100 points)

1. CI workflow exists — 12

2. Env schema validation present — 10

3. Typecheck script exists — 10

4. Test script + test files exist — 12

5. Lint configured — 10

6. Security headers configured (web stacks) — 10

7. Centralized logging present — 8

8. Observability hook present (Sentry/OpenTelemetry/etc) — 8

9. Dependency hygiene — 10

10. Docs baseline (README + setup) — 10

Outputs include:

• score /100

• detected stack summary

• categorized issues

• actionable recommendations

Local Registry Model

Registry root:

~/.boilerforge/registry

Template layout:

<template>/
  template.yaml
  files/
  migrations/   (optional)

template.yaml accepts YAML (not just JSON), and is strictly validated for required fields (name, version, createdAt) with clear parse/validation errors.

Lockfile (boilerforge.lock.json) stores template name/version/source for deterministic upgrades.

Lifecycle Compatibility

Existing lifecycle workflows remain supported:

boilerforge init <project-name> [--workflow=claude]
boilerforge update [--dry-run]
boilerforge protect add <category> <name>
boilerforge protect remove <category> <name>
boilerforge status

MCP Server Tools (unchanged)

• list_boilerplates

• get_boilerplate

• search_boilerplates

• scaffold_project

• check_project_updates

Running the package without CLI args in non-interactive MCP context still starts the MCP server.

CI/CD

GitHub Actions workflows included:

• ci.yml: install, lint, typecheck, test, build, doctor --ci --min-score 70, CLI smoke checks, and npm package integrity (npm pack) verification.

• publish.yml: release-driven publish pipeline (lint + typecheck + test + build + doctor gate + npm publish with provenance).

Minimal CI snippet for your own repos:

- name: Architecture gate
  run: boilerforge doctor . --ci --min-score 70

doctor --ci exits non-zero when below threshold, so it can be used as a hard merge/release gate.

Development

git clone https://github.com/MRKT365-India/boilerforge.git
cd boilerforge
npm install
npm run build
npm test