forge-ai-init

forge-ai-init

AI Governance Layer — one command to add AI coding rules, skills, hooks, and quality gates to any project.

AI tools generate code fast, but without governance: no architecture patterns, no security rules, no quality gates, no technical conscience. forge-ai-init adds the missing layer.

Quick Start

npx forge-ai-init

Interactive wizard detects your stack, asks your preferences, generates governance files. Done.

The Problem

GitClear's analysis of 211M lines of code shows AI-assisted projects have 60% less refactored code, 48% more copy-paste patterns, and 2x code churn. Ox Security found 10 recurring anti-patterns in 80-100% of AI-generated codebases.

The result: AI limbo engineering — code that "works" but is unmaintainable, insecure, and unscalable.

forge-ai-init is the technical conscience your AI tools are missing.

What It Generates

your-project/
├── CLAUDE.md                          # AI governance rules (Claude Code)
├── .cursorrules                       # Cursor governance rules
├── .windsurfrules                     # Windsurf governance rules
├── .github/copilot-instructions.md    # GitHub Copilot governance rules
├── .claude/
│   ├── settings.json                  # Permission model + hooks
│   └── skills/
│       ├── quality-gate/SKILL.md      # Pre-PR quality checks
│       ├── security-check/SKILL.md    # OWASP + dependency audit
│       ├── code-conscience/SKILL.md   # AI code discipline enforcer
│       ├── test-autogen/SKILL.md      # Auto-generation of required tests
│       ├── arch-review/SKILL.md       # Architecture enforcement
│       ├── test-first/SKILL.md        # TDD enforcement
│       ├── dependency-audit/SKILL.md  # Dependency health checks
│       ├── scalability-review/SKILL.md # Scalability assessment
│       ├── migration-audit/SKILL.md   # Legacy codebase assessment (--migrate)
│       └── tech-debt-review/SKILL.md  # Tech debt prioritization (--migrate)
├── MIGRATION.md                       # Migration roadmap (--migrate)
├── docs/adr/ADR-0001-*.md            # Initial migration ADR (--migrate)
├── .mcp.json                          # MCP server configs
├── .githooks/
│   ├── pre-commit                     # test-autogen guard
│   └── pre-push                       # test-autogen CI parity
├── scripts/hooks/install-hooks.sh     # core.hooksPath installer
├── .forge/                            # (enterprise tier)
│   ├── policies/                      # Security, quality, compliance policies
│   ├── scorecard.json                 # Scorecard configuration
│   └── features.json                  # Feature toggles seed
└── .github/workflows/                 # (or .gitlab-ci.yml)
    ├── ci.yml                         # Lint, build, test, audit
    ├── secret-scan.yml                # TruffleHog scanning
    ├── test-autogen-learning.yml      # Weekly metadata learning PR
    ├── scorecard.yml                  # Project scorecard (enterprise)
    └── policy-check.yml               # Policy evaluation (enterprise)

AI Governance Rules

Every generated rules file includes governance sections that prevent common AI-driven development anti-patterns:

• AI Code Governance — Reject copy-paste patterns, enforce refactoring, require architectural intent, ban speculative features
• AI Anti-Patterns to Block — 10 specific patterns: shallow error handling, dependency bloat, dead code, implicit coupling, missing validation
• Scalability & Performance — Database query patterns, API design, caching, async processing, observability (standard+)
• Legacy Migration Governance — Strangler fig pattern, characterization tests, incremental typing, feature flags (--migrate)

Stack Detection

Auto-detects your project's language, framework, build tool, package manager, test framework, and CI provider.

Category	Supported
Languages	TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin
Frameworks	Next.js, React, Vue, Svelte, Express, NestJS, FastAPI, Django, Flask, Spring, Astro, Remix, Nuxt, SvelteKit
Package Mgrs	npm, pnpm, yarn, bun, pip, poetry, cargo, go
CI/CD	GitHub Actions, GitLab CI, CircleCI, Jenkins
Test Frameworks	Jest, Vitest, pytest, Mocha, Playwright, Cypress
Build Tools	Vite, webpack, Turbopack, esbuild, tsup, Rollup, Parcel

Governance Tiers

Tier	For	Skills	What's generated
Lite	Solo dev, prototypes	0	Rules + hooks
Standard	Teams, production	4	Rules + skills + MCP + CI
Enterprise	Organizations	8	Standard + policies + scorecard + feature toggles

Skills by Tier

Skill	Lite	Standard	Enterprise
quality-gate	-	✓	✓
security-check	-	✓	✓
code-conscience	-	✓	✓
test-autogen	-	✓	✓
arch-review	-	-	✓
test-first	-	-	✓
dependency-audit	-	-	✓
scalability-review	-	-	✓
migration-audit	-	--migrate	--migrate
tech-debt-review	-	--migrate	--migrate

CLI Usage

# Interactive (default)
npx forge-ai-init

# Non-interactive
npx forge-ai-init --tier standard --tools claude,cursor --yes

# Legacy migration mode
npx forge-ai-init --migrate --tier enterprise --yes

# Preview without writing
npx forge-ai-init --dry-run

# Overwrite existing files
npx forge-ai-init --force

# Target a specific directory
npx forge-ai-init --dir /path/to/project

# Update existing governance files (auto-detects tier/tools)
npx forge-ai-init update

# Update and upgrade to enterprise tier
npx forge-ai-init update --tier enterprise

# Assess migration readiness
npx forge-ai-init assess

# Assess with JSON output
npx forge-ai-init assess --json

# Watch mode — continuous scanning during development
npx forge-ai-init migrate --watch

# Scan only staged files (fast pre-commit check)
npx forge-ai-init migrate --staged

# Save a quality baseline snapshot
npx forge-ai-init baseline

# Compare current scan against saved baseline
npx forge-ai-init baseline --compare

# Architecture planning with risk analysis
npx forge-ai-init plan

# Continuous health monitoring
npx forge-ai-init doctor

# CI quality gate enforcement (exit code 0/1)
npx forge-ai-init gate --phase production --threshold 80

# Auto-generate and enforce tests for changed files
npx forge-ai-init test-autogen --staged --write --check --tenant "$FORGE_TENANT_ID" --tenant-profile-ref "$FORGE_TENANT_PROFILE_REF"
npx forge-ai-init test-autogen --check --json --tenant "$FORGE_TENANT_ID" --tenant-profile-ref "$FORGE_TENANT_PROFILE_REF"

# Create project from golden path template
npx forge-ai-init scaffold --template nextjs-app --name my-app

test-autogen executes git commands through argument-safe invocation (no shell interpolation).

Options

Flag	Description	Default
--dir <path>	Target project directory	.
--tenant <id>	Tenant identifier (or FORGE_TENANT_ID)	required
--tenant-profile-ref <path>	Tenant profile file path (or FORGE_TENANT_PROFILE_REF)	required
--tier <level>	Governance tier: lite, standard, enterprise	standard
--tools <list>	AI tools: claude, cursor, windsurf, copilot	claude
--migrate	Legacy migration mode (extra rules + skills)	false
--force	Overwrite existing files	false
--dry-run	Show what would be created	false
--yes	Skip interactive prompts	false
--staged	Scan only git-staged files (migrate command)	false
--watch	Watch for changes and re-scan (migrate command)	false
--compare	Compare against saved baseline (baseline command)	false
--phase <p>	Quality gate phase: foundation, stabilization, production	auto
--threshold <n>	Quality gate minimum score (0-100)	from config
--check	Enforce required generated artifacts (test-autogen)	false
--write	Write missing generated artifacts (test-autogen)	false
--template <id>	Scaffold template ID	-
--name <name>	Project name (scaffold command)	-

Test-Autogen Local x CI Matrix

| Guardrail | Local (developer machine) | CI / PR parity | | ---------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------ | ------- | | Required tests for changed files | npx forge-ai-init test-autogen --staged --write --check --tenant "$FORGE_TENANT_ID" --tenant-profile-ref "$FORGE_TENANT_PROFILE_REF" (pre-commit) | forge-ai-action with command: test-autogen-check | | Full branch validation before push | npx forge-ai-init test-autogen --check --json --tenant "$FORGE_TENANT_ID" --tenant-profile-ref "$FORGE_TENANT_PROFILE_REF" (pre-push) | test_autogen_phase=warn | phase1 | phase2 | | Missing tests feedback | Hook failure with missing files | PR comment + annotations + status check | | Learning loop | .forge/test-autogen-telemetry.jsonl + baseline | Weekly workflow .github/workflows/test-autogen-learning.yml opens manual-review PR |

The default PR gate in this repository uses forge-ai-action command: diff to block regressions introduced by the PR delta without failing on pre-existing repository debt.

CI Tenant Contract

The quality-gate job reads tenant configuration from the inline committed file:

.forge/tenant-profile.yaml

No external repository checkout or secrets are required. The file is committed directly in this repo and validated by the CI job at runtime. If the file is missing the job fails fast with a clear error message.

Update Governance Files

Run update to re-generate governance files with the latest rules and patterns:

npx forge-ai-init update

Auto-detects your current tier, tools, and migration mode from existing files. Only overwrites files whose content actually changed — unchanged files are preserved.

# Upgrade from lite to standard tier
npx forge-ai-init update --tier standard

# Add Cursor support to existing setup
npx forge-ai-init update --tools claude,cursor

Governance Audit

Run check to audit any project's governance maturity — no generation needed:

npx forge-ai-init check

Scores 7 categories with 20+ weighted checks:

Category	What it checks
AI Rules	CLAUDE.md, AI governance rules, anti-patterns, multi-tool coverage
Skills	Governance skills count and coverage
Hooks & Safety	Claude settings, PreToolUse safety hooks, PostToolUse formatting
CI/CD	Pipeline presence, secret scanning, security scanning
Security	.env protection, SECURITY.md, MCP config
Code Quality	Linting, type checking, formatting, test framework
Policies	Enterprise policies, scorecard config

Grades: A (90+) → B (75+) → C (60+) → D (40+) → F (<40)

Use the audit to assess legacy projects before migration:

# Audit a legacy project
npx forge-ai-init check --dir /path/to/legacy-app

# Then add governance
npx forge-ai-init --migrate --tier enterprise --dir /path/to/legacy-app

Code Scanner

Run migrate to scan source code for anti-patterns, tech debt, and security issues:

npx forge-ai-init migrate

Detects 115 patterns across 10 categories (language-aware — rules only fire on matching file types):

Category	What it finds
Security	Hardcoded secrets, innerHTML assignment, SQL injection, code injection, unsafe HTML
Error Handling	Empty catch blocks, console-only error handling
Architecture	God files (>500 lines), function sprawl (>15 functions)
Engineering	@ts-ignore, sync I/O, index-as-key, console.log, TODO/FIXME, forEach+push
Async	Async Promise constructor, deep promise chains, setTimeout zero-delay
Type Safety	Explicit any, type assertions, non-null assertions
React	Fetch in useEffect, excessive useState (4+)
Scalability	Full lodash import
Accessibility	Images without alt text
Hardcoded Values	Hardcoded URLs that should be config
Python	Bare except, except-pass, os.system, subprocess shell, pickle, SQL format injection, typing.Any, type-ignore, import *, globals, mutable defaults, assert
Go	Bare error return, panic, empty interface, SQL concatenation, blank import, global mutex, goroutine leak
Rust	Unsafe blocks, unwrap/expect, excessive clone, todo! macro, allow(lint) suppression
Java	System.out.println, raw JDBC Statement, @SuppressWarnings, Thread.sleep, hardcoded credentials, legacy Date, empty catch, printStackTrace
Kotlin	!! non-null assertion, runBlocking, empty catch, @Suppress, TODO markers
Svelte	{@html} XSS risk, reactive event handlers, reactive fetch calls

# Scan with colored terminal output
npx forge-ai-init migrate

# Machine-readable JSON output
npx forge-ai-init migrate --json

# Scan a specific directory
npx forge-ai-init migrate --dir /path/to/project

# Watch mode — re-scans on every file change
npx forge-ai-init migrate --watch

# Scan only git-staged files (fast pre-commit check)
npx forge-ai-init migrate --staged

# Staged scan with JSON output (for pre-commit hooks)
npx forge-ai-init migrate --staged --json

Migration Assessment

Run assess to get a full health assessment of any codebase before migration:

npx forge-ai-init assess

Analyzes 5 categories with 35+ checks:

Category	What it checks
Dependencies	Legacy packages (jQuery, Moment, etc.), excessive deps, missing lockfile, no engine constraint
Architecture	God files (>500 lines), function sprawl (>20 per file), high coupling (>15 imports), flat structure
Security	Hardcoded secrets, AWS keys, private keys, eval/innerHTML/SQL injection, unrestricted CORS, missing .gitignore/.env
Quality	Test framework, linting, type checking, formatting, CI/CD, empty catch blocks, TODO accumulation, test coverage ratio
Migration Readiness	Legacy stack detection, global state pollution, TypeScript adoption, documentation, test safety net

Health score (0-100) with A-F grading per category and overall. Migration readiness: ready / needs-work / high-risk.

Auto-detects migration strategy:

• Strangler fig — backends (Express, FastAPI, Django, Flask)
• Branch by abstraction — frontends (React, Vue, Next.js)
• Parallel run — Java applications

# Assess with colored terminal output
npx forge-ai-init assess

# Machine-readable JSON output
npx forge-ai-init assess --json

# Assess a specific directory
npx forge-ai-init assess --dir /path/to/legacy-app

# Full migration workflow
npx forge-ai-init assess --dir /path/to/legacy-app
npx forge-ai-init --migrate --tier enterprise --dir /path/to/legacy-app

Configuration

Customize governance rules per-project with .forgerc.json:

{
  "extends": "recommended",
  "rules": {
    "console-log": false,
    "empty-catch": { "severity": "critical" }
  },
  "categories": {
    "react": { "enabled": false }
  },
  "ignore": ["legacy/", "*.generated.*"],
  "thresholds": { "commit": 70, "pr": 80, "deploy": 90 },
  "maxFiles": 1000
}

Presets

Preset	Commit	PR	Deploy	Relaxed Rules
strict	80	85	90	None
recommended	60	70	80	None
lenient	40	50	60	console-log, todo-marker, type-assertion disabled

Config is auto-generated during scaffolding with a tier-appropriate preset. Supports .forgerc.json, .forgerc, and forge.config.json.

Report Export

Export scan results for CI/CD pipelines and compliance workflows:

# Export as SARIF (GitHub Security tab)
npx forge-ai-init migrate --format sarif --output report.sarif

# Export as Markdown
npx forge-ai-init migrate --format markdown --output report.md

# Export as JSON
npx forge-ai-init migrate --format json --output report.json

SARIF reports integrate with GitHub's code scanning alerts — add to your CI workflow:

- run: npx forge-ai-init migrate --format sarif --output results.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Baseline Tracking

Track quality score over time with snapshots:

# Save a baseline snapshot
npx forge-ai-init baseline

# After making changes, compare against the baseline
npx forge-ai-init baseline --compare

Compare output:

  Score: 72 → 85 (▲ +13)
  Grade: C → B changed
  Files: 42 → 44

  ✓ 8 findings resolved
  ✗ 2 new findings

  Category changes:
    error-handling       5 → 2 (-3)
    security             3 → 1 (-2)
    engineering          2 → 5 (+3)

Baselines are stored in .forge/baseline.json as a history array — each baseline call appends a new snapshot for trend tracking.

Architecture Planning

Run plan to generate an architecture-first analysis of any project:

npx forge-ai-init plan
npx forge-ai-init plan --json

Analyzes project structure, detects risks, generates recommendations, suggests ADRs, and defines quality gates:

• Structure analysis — file counts, test ratio, entry points, top-level directories
• Risk detection — missing CI, no type checking, low test ratio, security findings, architecture issues
• Recommendations — prioritized as must/should/could with specific actions
• ADR suggestions — architecture style, testing strategy, monorepo strategy
• Scaling strategy — framework-specific guidance (Edge-first for Next.js, horizontal for Express, ASGI for FastAPI)
• Quality gates — 3-phase progressive enforcement (40% foundation → 60% stabilization → 80% production)

Health Monitoring

Run doctor for continuous architecture health checks:

npx forge-ai-init doctor
npx forge-ai-init doctor --json

11 health checks across 5 categories:

Category	Checks
Architecture	God files, function sprawl
Security	Critical findings, security vulnerabilities
Governance	CI/CD, linting, type checking, CLAUDE.md, ARCH.md
Quality	Score threshold, error handling patterns

Integrates with baseline tracking for trend detection (improving/stable/degrading). Calculates coupling and complexity scores.

Quality Gate

Run gate to enforce quality thresholds in CI/CD:

# Auto-detect phase and threshold
npx forge-ai-init gate

# Explicit phase and threshold
npx forge-ai-init gate --phase production --threshold 80

# Machine-readable for CI
npx forge-ai-init gate --json

Exit code 0 = passed, 1 = failed. Phase auto-detection from score: foundation (<60), stabilization (60-80), production (80+).

Blocking rules per phase:

• Foundation/Stabilization — blocks on critical severity findings
• Production — blocks on critical AND high severity findings

Reads thresholds from .forgerc.json deploy threshold. Use in CI:

- name: Quality gate
  run: npx forge-ai-init gate --phase production --threshold 80

Golden Path Templates

Run scaffold to create new projects from opinionated templates with governance built in:

# List available templates
npx forge-ai-init scaffold

# Create a project
npx forge-ai-init scaffold --template nextjs-app --name my-app
npx forge-ai-init scaffold --template express-api --name my-api
npx forge-ai-init scaffold --template fastapi-service --name my-svc
npx forge-ai-init scaffold --template ts-library --name my-lib
npx forge-ai-init scaffold --template cli-tool --name my-cli

Every template includes .gitignore, CLAUDE.md, and .forgerc.json from day one. No governance debt.

Template	Description	Includes
nextjs-app	Next.js App Router with TypeScript	React 19, ESLint, Jest, tsconfig
express-api	Express API with Zod validation	Express 5, Zod, tsx, tsup
fastapi-service	FastAPI service with pytest	FastAPI, uvicorn, ruff, mypy
ts-library	TypeScript library with tsup	tsup, Jest, ESM
cli-tool	CLI tool with @clack/prompts	@clack/prompts, picocolors, tsx

Migration Planning

Run migrate-plan to generate a detailed, actionable migration roadmap:

npx forge-ai-init migrate-plan
npx forge-ai-init migrate-plan --json

Analyzes your codebase and produces:

• Strategy detection — Strangler Fig (backends), Branch by Abstraction (frontends), Parallel Run (Java), or Incremental Modernization
• Strangler boundaries — god files and sprawl modules that should be decomposed first, classified by type (api/service/data/ui)
• Dependency risks — detects 11 legacy packages (moment, jquery, request, lodash, bluebird, etc.) with modern replacements
• Typing plan — prioritized JS→TS file conversion order (entry points and utilities first, large files last)
• Phased roadmap — Stabilize (fix critical, add tests, CI) → Modernize (decompose, type, test) → Harden (full governance)
• Effort estimation — calculated from boundary complexity, typing needs, and dependency risks

# Full migration workflow
npx forge-ai-init migrate-plan                    # Get the roadmap
npx forge-ai-init assess                          # Detailed health assessment
npx forge-ai-init --migrate --tier enterprise     # Add governance layer
npx forge-ai-init baseline                        # Set starting baseline
# ... do the work ...
npx forge-ai-init baseline --compare              # Track progress
npx forge-ai-init gate --phase stabilization      # Verify gate passes

CI Pipeline Generator

Generate a complete CI quality gate pipeline in one command:

npx forge-ai-init ci --provider github-actions
npx forge-ai-init ci --provider gitlab-ci --phase production
npx forge-ai-init ci --provider bitbucket --threshold 80

Provider	Output File	Features
github-actions	.github/workflows/forge-quality.yml	Checkout, Node setup, scan, gate
gitlab-ci	.gitlab-ci.yml	Test stage, artifacts, node:22 image
bitbucket	bitbucket-pipelines.yml	Pull request pipeline, node:22 image

Reads thresholds from .forgerc.json. Add --phase to set quality phase, --threshold for custom minimum score.

PR Quality Delta

Analyze the quality impact of a PR or staged changes:

npx forge-ai-init diff                    # Compare against main
npx forge-ai-init diff --base develop     # Compare against develop
npx forge-ai-init diff --staged           # Scan staged files only
npx forge-ai-init diff --json             # Machine-readable output

Shows:

• Changed files count
• Score delta (before → after) with trend arrow
• New findings introduced by the PR
• Summary verdict (improved/degraded)

Compares against saved baseline (from forge-ai-init baseline) when available.

Legacy Migration Mode

Use --migrate to add governance to existing legacy projects. This mode adds:

• Migration governance rules — Strangler fig pattern, ADRs, incremental typing, backward-compatible APIs, feature flags for migration
• migration-audit skill — Full codebase health assessment: code quality, architecture, tests, security, scalability risks
• tech-debt-review skill — Categorized debt identification with impact/effort scoring matrix
• dependency-audit skill — Security vulnerabilities, outdated packages, license compliance, bundle impact
• Progressive Quality Gates — phased enforcement that increases thresholds as migration progresses:

Phase	Threshold	Focus
Initial	40%	Critical security, basic tests
Stabilization	60%	Linting, type safety, test coverage
Production	80%	Full governance enforcement

• Migration CI Workflow — migration-gate.yml running governance audit + migration policy checks on every PR
• Characterization test enforcement — blocks migration without behavioral parity tests
• ADR requirement — warns on strategy changes without Architecture Decision Records

# Add governance to a legacy project
npx forge-ai-init --migrate --tier standard --yes

# Enterprise migration with full policy engine
npx forge-ai-init --migrate --tier enterprise --yes

AI Tool Support

Tool	Files Generated
Claude Code	CLAUDE.md, .claude/settings.json, .claude/skills/, .mcp.json
Cursor	.cursorrules
Windsurf	.windsurfrules
GitHub Copilot	.github/copilot-instructions.md

Enterprise Policy Engine

The enterprise tier generates a .forge/ directory with policy files compatible with @forgespace/core:

• Security policy — secret exposure detection, authentication enforcement
• Quality policy — lint checks, test requirements, coverage thresholds
• Compliance policy — audit logging, correlation IDs
• Framework policies — a11y (React/Next.js), bundle size (Next.js), API validation (Express/NestJS/FastAPI)
• Scorecard config — framework-aware weights for automated project scoring
• CI workflows — scorecard.yml and policy-check.yml for PR-level enforcement

CI/CD Integration

GitHub Action (Recommended)

The easiest way to add quality gates to your CI:

name: Quality Gate
on: [pull_request]

permissions:
  contents: read
  pull-requests: write

jobs:
  forge:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: Forge-Space/forge-ai-action@v1
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          threshold: 75

Posts a quality report on every PR with score, delta, findings, and inline annotations. See forge-ai-action for full docs.

GitHub Actions (Manual)

Quality Gate on Pull Requests

name: AI Governance
on: [pull_request]

jobs:
  governance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Scan for anti-patterns
        run: npx forge-ai-init migrate --format json --output scan.json

      - name: Check quality gate
        run: |
          SCORE=$(node -e "console.log(JSON.parse(require('fs').readFileSync('scan.json','utf8')).score)")
          echo "Score: $SCORE/100"
          if [ "$SCORE" -lt 60 ]; then
            echo "::error::Quality gate failed ($SCORE < 60)"
            exit 1
          fi

      - name: Upload SARIF to Security tab
        if: always()
        run: npx forge-ai-init migrate --format sarif --output results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif

Staged Scan (Fast PR Check)

For faster CI on large repos, scan only changed files:

- name: Scan changed files only
  run: |
    git diff --name-only origin/main...HEAD > /tmp/changed.txt
    npx forge-ai-init migrate --staged --json

Governance Audit

Check if a project meets governance standards before deploy:

- name: Governance audit
  run: |
    npx forge-ai-init check --dir . 2>&1 | tee audit.txt
    # Parse grade from output
    if grep -q "Grade: F" audit.txt; then
      echo "::error::Governance audit failed"
      exit 1
    fi

Full Pipeline (Scan + Assess + Audit)

name: AI Governance Suite
on:
  pull_request:
  push:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx forge-ai-init migrate --format sarif --output results.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: results.sarif

  assess:
    runs-on: ubuntu-latest
    if: github.event_name == 'pull_request'
    steps:
      - uses: actions/checkout@v4
      - name: Migration assessment
        run: npx forge-ai-init assess --format markdown --output assessment.md
      - name: Post assessment as PR comment
        uses: actions/github-script@v8
        with:
          script: |
            const fs = require('fs');
            const body = fs.readFileSync('assessment.md', 'utf8');
            await github.rest.issues.createComment({
              ...context.repo,
              issue_number: context.issue.number,
              body: `## AI Governance Assessment\n\n${body}`
            });

  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx forge-ai-init check

GitLab CI

ai-governance:
  image: node:22
  stage: test
  script:
    - npx forge-ai-init migrate --format json --output scan.json
    - |
      SCORE=$(node -e "console.log(JSON.parse(require('fs').readFileSync('scan.json','utf8')).score)")
      echo "Score: $SCORE/100"
      [ "$SCORE" -ge 60 ] || exit 1
  artifacts:
    reports:
      sast: results.sarif
    paths:
      - scan.json
  rules:
    - if: $CI_MERGE_REQUEST_IID

Pre-Commit Hook

Add to your project's pre-commit (works with Husky, lefthook, or plain git hooks):

#!/bin/sh
# .husky/pre-commit or .git/hooks/pre-commit

npx forge-ai-init migrate --staged --json > /tmp/forge-scan.json
SCORE=$(node -e "console.log(JSON.parse(require('fs').readFileSync('/tmp/forge-scan.json','utf8')).score)")

if [ "$SCORE" -lt 60 ]; then
  echo "Governance check failed: $SCORE/100 (minimum: 60)"
  echo "Run 'npx forge-ai-init migrate' to see details"
  exit 1
fi

Configuring Thresholds

Use .forgerc.json to set different thresholds per stage:

{
  "extends": "recommended",
  "thresholds": {
    "commit": 60,
    "pr": 70,
    "deploy": 80
  }
}

Then reference in CI:

THRESHOLD=$(node -e "
  const c = JSON.parse(require('fs').readFileSync('.forgerc.json','utf8'));
  console.log(c.thresholds?.pr ?? 70)
")
npx forge-ai-init migrate --json | node -e "
  let d='';process.stdin.on('data',c=>d+=c);
  process.stdin.on('end',()=>{
    const r=JSON.parse(d);
    console.log('Score:',r.score,'/ Threshold:',${THRESHOLD});
    process.exit(r.score < ${THRESHOLD} ? 1 : 0)
  })
"

Badge Generation

Add a governance score badge to your README:

# Generate badge URL from scan score
SCORE=$(npx forge-ai-init migrate --json | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>console.log(JSON.parse(d).score))")
GRADE=$(npx forge-ai-init migrate --json | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>console.log(JSON.parse(d).grade))")
COLOR=$( [ "$SCORE" -ge 90 ] && echo "brightgreen" || [ "$SCORE" -ge 75 ] && echo "green" || [ "$SCORE" -ge 60 ] && echo "yellow" || echo "red" )

echo "![Governance](https://img.shields.io/badge/governance-${GRADE}%20${SCORE}%25-${COLOR})"

License

MIT