MindForge v12.0.0: An Agentic Framework for Claude Code — What It Ships, How to Install It, and What's Actually Enforced

Agentic frameworks for Claude Code have exploded over the last year — swarms of subagents, skill libraries, protocol layers stacked on top of a single model. Most of them describe what they ship in one flattened register: "AI capabilities." MindForge (mindforge-cc on npm) is a governance and orchestration layer in that same category, sitting on top of Claude Code — it is not a replacement for it, and it does not run without it — but it's one of the more mature, more self-critical entries: it treats its own surface area as five mechanically distinct pieces rather than one undifferentiated pile, and it draws an explicit line between the parts that are genuinely enforced and the parts that are just well-organized advice. As of this writing, v12.0.0 is tagged and live on npm — both latest and stable point to it, with a real GitHub Release at the matching tag — and its CHANGELOG entry says, verbatim, this is "MindForge's first release deliberately cut for real external users." That framing, and how it holds up against the actual source tree, is what this piece checks.

Concretely, MindForge ships as three things: an npm package that installs slash commands, skills, personas, subagents, and hooks into a .claude/ (and mirrored .agent/) directory; a set of Claude Code plugin-marketplace entries; and a separate MCP server plus TypeScript SDK. Almost everything it ships — the commands, the skills, the personas, the workflow scripts, the governance docs — works by being loaded into the model's context. None of that is code the model is forced to obey. The one exception, and the one piece of this system that is a real technical enforcement mechanism, is a small set of Claude Code hooks. That distinction — advisory context vs. enforced blocking — is the single most important thing to understand about this project, and it's the project's own README that draws the line, not outside auditors.

This matters because MindForge's own CHANGELOG and its repo-local .claude/CLAUDE.md spend real effort disowning parts of their own marketing language. The "Unified Protocol Engine" framing that shows up in some MindForge-derived global configs — SwarmController, PersonaFactory, WaveExecutor, soul-engine.js, shard-controller.js — is explicitly called out in the repo's own .claude/CLAUDE.md as aspirational naming with no backing code: those are "role names in the specs under .mindforge/engine/, not importable code." That kind of self-correction, verified directly against the source tree rather than taken on faith, is the throughline of this whole release.

The real working loop that MindForge scaffolds is plan-phase → execute-phase → verify-phase → ship, and it is detailed rather than just a name: plan-phase spawns a research subagent and writes atomic XML plan files with explicit <verify> steps; execute-phase runs dependency-aware waves against a five-level escalating validation ladder (static, unit, build, integration, edge) and writes a Deviation Report per task; verify-phase walks the human through REQUIREMENTS.md deliverables and writes UAT.md, spawning a debug subagent on failure; ship gates on UAT.md reading "All passed," runs tsc --noEmit, eslint, npm test, and npm audit, and generates the PR description. It's real machinery, not command-name theater — though even here there's a live wrinkle worth knowing about: ship.md's Step 4 currently hardcodes a literal branch name in its git push rather than deriving the active branch, so anyone not literally on that named branch could push to the wrong place.

MindForge's surface area breaks into five genuinely distinct mechanisms, and the differences between them are mechanical, not just naming conventions. Here's what it actually gives you, at a glance, verified count by verified count:

"Enforced" in that last row only ever means on Claude Code, via the npx installer's --local or --global target — see the next section for exactly what that does and doesn't cover.

Commands are 221 slash-command .md files under .claude/commands/mindforge/, mirrored exactly in .agent/mindforge/ — verified by direct file count, not just README's say-so. They're prompt specs the model reads and follows; they don't execute independently of the model choosing to follow them.

Skills split into two tiers totaling 354 files: 232 "engine tier" skills under .mindforge/skills/, auto-triggered by keyword match, and 122 "extended tier" skills under .agent/skills/, explicitly invoked by name. The engine tier enforces a strict schema via tests/skills-platform.test.js — semver version, a status field, at least ten trigger terms, a "Mandatory actions" section — while the extended tier only requires a name. Here's the part worth being honest about: the file that's supposed to do the actual trigger-matching, bin/engine/skill-.js, is dead code — a four-line stub ( loadSkill: () => null, matchTriggers: () => []) with zero real callers, and the CHANGELOG says so directly. The real trigger-matching mechanism is .mindforge/engine/skills/.md, an LLM-followed protocol spec, not deterministic code. That means "skill triggering" in MindForge is non-deterministic by design — the model decides what counts as a match, not a parser.

Personas are 216 named role-overlay files under .mindforge/personas/, loaded via /mindforge:agent <name> into the same session context — a role swap, not a new agent. This is a meaningfully different mechanism from subagents, and MindForge's own docs are explicit about the distinction rather than blurring it for effect.

Subagents are 164 real Claude-Code-native subagent definition files under subagents/categories/, each with proper frontmatter (name/description/tools/model) designed for Claude Code's isolated-context subagent mechanism — genuinely separate execution contexts, unlike personas. 152 of those files are attributed to VoltAgent's MIT-licensed awesome-claude-code-subagents, with the full license text reproduced; that attribution checks out against the vendored upstream repo. One correction worth flagging: the README's claimed "152 adapted / 12 original" split undercounts the adapted set by two — dotnet-framework-48-expert.md and powershell-51-expert.md are near-byte-identical VoltAgent copies with dots stripped from the filename for path safety, so the real split is closer to 154 adapted / 10 original. Small, but it's the kind of thing worth naming rather than repeating uncritically.

Dynamic workflows are 35 JavaScript scripts across five tiers (Research 5, Dev 14, Ops 6, Intelligence 7, Beast 3) under .mindforge/dynamic-workflows/scripts/, and the ones that were read in full are genuinely substantial multi-agent orchestration code — security-hardening.js, for instance, runs five parallel OWASP scout agents, then for every critical/high finding spins up a nested three-vote adversarial verification round (refute / challenge-exploitability / assess-impact) requiring a real two-of-three quorum before accepting a finding. That's not a cosmetic label. But here's the structural fact that matters most: the actual execution primitives these scripts call — agent(), parallel(), phase() — are not implemented anywhere in the MindForge repository. They're supplied entirely by Claude Code's own host-level Workflow tool at runtime. MindForge ships the script library, the JSON registry, and the CLI browser; it does not ship a self-contained execution engine. Every one of these scripts also contains a top-level return statement, so none of them are valid standalone Node.js files — they only run wrapped by that external harness. This is a real architectural fact, not a defect, but it's exactly the kind of thing a launch article shouldn't gloss over: "35 dynamic workflows" means 35 curated orchestration scripts that target a host capability, not 35 things MindForge alone can run.

This is the section that most agent-tooling projects don't write, and MindForge's README does, in a dedicated "What is actually enforced" section: hooks are the only real blocking mechanism in the entire framework, and they only block on Claude Code, via the npx installer's --local target. They are explicitly not enforced on Cursor, Copilot, Gemini, or Antigravity; not on --global installs; not on self-installs; and not on Windows.

The live, dogfooded numbers behind that claim hold up under direct verification: the repo's own .claude/settings.json registers exactly 8 hooks (2 PostToolUse, 4 PreToolUse, 2 SessionStart). Of those, 7 are executed by the installer's preflight check (one, mindforge-check-update, is deliberately skipped). Of the 7 executed, only 3 are "deny-class" — capable of returning a hard block: trust-gate, mindforge-block-no-verify, and mindforge-config-protection. All three were confirmed live to return exit code 2 on trigger. Everything else in this system — the 221 commands, the 354 skills, the 216 personas, the 35 workflows, the governance and audit docs — can be ignored by the model at any time. A launch article shouldn't imply that installing MindForge "activates" or "enforces" its governance or security-scan language across arbitrary tools or channels. It doesn't. It narrows enforcement to three specific hooks on one specific install channel, and says so.

MindForge maintains a tamper-evident audit log at .planning/AUDIT.jsonl, hash-chained with SHA-256 via a shared hasher ( bin/governance/audit-hash.js) used by both the writer and the verifier. Running the verifier live against this repo's own log returned "audit chain valid: 6396 entries." SECURITY.md scopes the claim precisely — the chain detects mid-file mutation and deletion, and explicitly does not detect tail truncation or replay — and a dedicated honesty test suite (tests/audit-claims-honesty.test.js) checks that the documentation doesn't overclaim beyond that, including confirming the writer doesn't sign entries and the docs never call this a Merkle tree.

The more interesting story is what the project's own pre-ship audits actually catch, because it's a real mix of genuine bugs and genuine overclaiming, disclosed rather than buried. The v11.9.9 release describes an eight-agent audit workflow run as a release gate before shipping to real external users, and it's not a rubber stamp: that pass found 5 CRITICAL issues, including a jailbreak skill named "godmode" that had been shipping live, a security check with no real CLI entrypoint (so it could structurally never fail), and a --minimal install flag that silently shipped the full persona set anyway — plus 9 HIGH findings. Verified directly: neither the godmode skill nor any of its assets exist anywhere in the shipped tree, and a packaging-allowlist test explicitly asserts its absence. That same audit pass also fixed a set of docs (help.md, status.md, health.md, security-scan.md) that had been overclaiming a post-quantum-signature feature (PQAS) and biometric gating as active; the real code is honest about this now — bin/governance/quantum-crypto.js labels its Dilithium-5 implementation "SIMULATED... NOT real ML-DSA/FIPS-204," gated off by default in config. Earlier releases show the same pattern repeating: v11.9.8 found two real crashing bugs plus 12 pure documentation inaccuracies out of 113 claims checked; v11.9.6 found a crashing /mindforge:learn command and an auth-token-leaking browser daemon.

Two things are worth naming honestly rather than hiding. First, that PQAS-overclaim pattern had a residual instance the 11.9.9 audit missed: .mindforge/governance/policies/sovereign-default.json still marked PQAS and biometric checks as "ENABLED," even though that file is dead config the real PolicyEngine never loads. Second, the same "feature that isn't wired to what it implies" pattern shows up in a place the audits hadn't caught as of this research pass: MindForge's README describes a "two-model adversarial PR review" and a "4-voice consensus council," but as currently wired, both mechanisms route every voice and every round to the exact same single backing model — the cross-review engine's caller-supplied model names are used only as display labels, and the council's four voices all resolve through an unmapped persona to the same tier-2 default. That gap between naming and behavior was not in the CHANGELOG as of v11.9.9 — it's the kind of thing this project's own audit discipline should catch in its next pass, and naming it here is more useful to a reader than pretending it doesn't exist.

Also worth knowing: several of the CLI/doc claims that have surfaced in past audits are still true today and still disclosed rather than fixed. /mindforge:health --repair silently drops the --repair flag (byte-identical output to plain health); spawn <persona> still exits 1 with "not implemented in v1.0"; and two doc inaccuracies that survived multiple audit passes are still live — docs/commands-reference.md still lists a CLI command, quantum-verify, that doesn't exist (confirmed by running it), and docs/tutorial.md still documents an --ads flag on /mindforge:plan-phase that was never wired into the actual command file.

MindForge advertises cost-aware, difficulty-aware model routing across five real providers — Anthropic, OpenAI, Gemini, Bedrock, and Ollama — and the provider layer is genuinely live: each provider makes real HTTPS calls and computes real per-call cost through a shared pricing registry. What's worth being precise about is what actually decides which model gets used in production: it's persona plus a caller-supplied security tier (0–3), not computed task difficulty. Tier 3 forces a dedicated security model; named personas map to fixed model settings; everything else falls to sensible defaults (Haiku for quick tasks, Sonnet as the general executor).

There are, in fact, three separate difficulty-aware routing systems built into this codebase, and none of them are live. A real 1–10 difficulty scorer exists and is unit-tested, but its only caller runs it in shadow mode — it logs what model it would have picked and changes nothing. A second system, a full "multi-cloud arbitrage" broker with its own passing tests, is required nowhere except by its own test file (it even lists a fourth "azure" provider with no corresponding implementation). A third, MIR-based steering engine is explicitly gated behind a shadow_mode config flag and is imported by the one module that's supposed to call it — but never actually invoked. This is disclosed territory: the CHANGELOG documents fixing a near-identical prior bug in the same routing module (a regex mismatch that made every config value resolve to undefined), so the pattern of "wired but not connected" recurring in cost routing isn't new to this codebase — it's just not fully cleaned up yet.

MindForge ships three real, independently-verifiable channels, not one. mindforge-mcp-server@12.0.0 is genuinely published on npm right now, matches the repo source exactly (including SLSA provenance), and registers exactly 8 MCP tools — 6 read-only (health, status, memory query/stats/find-related, audit log), one guarded write (memory_remember), and one guarded, open-world tool ( browse, which proxies to a separate pre-existing bearer-token-authenticated Playwright daemon and never spawns it itself). Worth flagging honestly, because the project's own README already does: the official MCP registry listing for this server lags one patch version behind what's actually published on npm, and README tells readers to check what that listing actually serves, or install from npm directly, rather than trusting the registry blindly.

mindforge-sdk@12.0.0 is also live on npm and matches source. Its batchExecute spawns real child processes with SIGTERM-then-SIGKILL escalation — and there's a named regression test in the SDK's own test suite that exists specifically to guard against a previously-shipped fake stub that used to return {executed:true} without doing anything. That's a good tell for how seriously this project treats its own past mistakes: it doesn't just fix a caught bug, it writes a test whose name records what the bug was.

The underlying persistence layer for MindForge's local knowledge graph is a genuinely zero-native-dependency setup: sql.js, a WASM-compiled SQLite, backing an 11.8MB file ( celestial.db) with real FTS4 full-text search, plus a separate SHA-256-checksummed, file-locked JSONL edge list for relationship data. The live dashboard at localhost:7339 is a real Express + SSE server, bearer-token-authenticated on mutating routes, rate-limited, localhost-only, with seven API-backed tabs. Worth being precise here too: the more elaborate dashboard sub-features described in some MindForge-adjacent marketing language — a Temporal Slider, Hindsight Steering Vectors, a $100/hr AgRevOps ROI hub — were not independently verified beyond confirming the dashboard's base HTTP response; treat those as unverified narrative, not confirmed capability.

MindForge ships five real, independently-checkable install channels — pick whichever matches how you actually work. As of this writing every one of them installs v12.0.0 directly.

npx (recommended) — writes .mindforge/ governance, memory, and planning into your project, and registers the 8 hooks described above:

npx mindforge-cc@latest --claude --local      # Claude Code, this project only
npx mindforge-cc@latest --antigravity --local # Antigravity, this project only
npx mindforge-cc@latest                       # interactive wizard, pre-selects a detected runtime

Run non-interactively (CI, piped, scripted) and it skips the wizard entirely and installs --claude by default, regardless of what's actually on the machine. For a system-wide install: npx mindforge-cc@latest --claude --global — note that npm install -g mindforge-cc@latest on its own only puts the mindforge/ mindforge-cc binaries on your PATH, it doesn't scaffold anything; you still need to run the --global command above once. Other supported runtimes use the same flag pattern (--cursor, --copilot, --gemini). A few advanced flags worth knowing: --runtime claude,cursor (combined runtimes in one pass), --minimal (essential scaffolding only, no persona library), --force (rewrite an existing schema file with the current, stricter one).

Claude Code plugin marketplace — writes no project files at all; only the plugin's hooks fire (see the enforcement section above for exactly what that does and doesn't cover):

/plugin marketplace add sairam0424/MindForge
/plugin install mindforge@mindforge

Want just a slice instead of everything? mindforge-lang@mindforge and 9 other focused sub-packs exist for narrower installs.

Standalone MCP server — if all you want is the 8 read/write-guarded stdio tools described earlier, without any of the command/skill/persona tree:

claude mcp add mindforge -- npx -y mindforge-mcp-server

Also listed on the official MCP Registry, though that listing is manually republished and can lag behind npm — install mindforge-mcp-server directly if you want to pin an exact version.

Homebrew:

brew install sairam0424/tap/mindforge

The formula pins to a specific npm tarball with a checked sha256 — currently pointed at mindforge-cc-12.0.0.tgz, confirming this channel is already caught up for this release too, not a stale mirror.

SDK — build on MindForge programmatically, without installing any of the rest:

npm i mindforge-sdk

Once installed through any of the above, the natural entry points are /mindforge:init-project to scaffold a new project under the framework, /mindforge:next for auto-discovery of what to do given current state, and the plan-phase → execute-phase → verify-phase → ship loop described earlier for anything substantive. The subagent library is best installed through the plugin marketplace above rather than through bin/spawn-agent.js, which — despite what its own README implies about installing subagents "by name" via that script — is a dry-run/verification tool only; without --dry-run it always exits 1 with "not implemented in v1.0."

By the time research for this piece began, the goalpost had already moved once — from v11.9.9's own framing as a "release-readiness milestone" to a live git branch, spotted mid-research, whose commit message named v12.0.0 as the actual "first-user-release cut." It moved again shortly after: merged to main via PR #298, with a formal CHANGELOG entry titled, verbatim, "[12.0.0] — First release aimed at real external users," but not yet tagged or published. As of this update, it's moved a third and final time: v12.0.0 is tagged, published, and live — latest and stable on npm both point to it, and mindforge-mcp-server and mindforge-sdk shipped alongside it at the same version. The CHANGELOG entry says plainly what that title implies and nothing more: "MindForge's first release deliberately cut for real external users, not just internal iteration. The major-version bump is a milestone marker for that shift, not a signal of a breaking API/behavior change — there is none in this release; every item below is a fix."

That's the honest way to read a major-version bump in this project: not a rewrite, a readiness gate. It shipped because a second, independent eight-agent audit — security and STRIDE threat modeling, staff-engineer code review, dependency and license review, a live production dry-run across all six supported runtimes, docs-accuracy checking, re-verification of the prior release's deferred backlog, test-coverage gap analysis, and a full trace of the CI/CD release pipeline — was run specifically to answer one question: was v11.9.9 actually ready for real external users? The answer was no, not quite. That audit surfaced 1 CRITICAL and 4 HIGH findings, plus 8 MEDIUM/LOW findings judged worth fixing before this exact cutover, and every one of them was independently adversarially re-verified — 10 out of 10 confirmed, zero refuted — before being fixed.

The CRITICAL finding is worth naming, because it's the same species of bug this piece's own research caught mid-flight, independently, the same week: a --global install printed a fabricated "PAYLOAD MANIFEST" claiming 216 personas, 122 skills, and more were now "active," while writing none of them. The success banner had been counting the source package tree instead of what a global install actually writes by design — an entry file, commands, and subagents only. It's fixed now, replaced with an honest message describing exactly what a global install does and doesn't include. The HIGH-severity fixes closed a related gap — an install banner still claiming a confirmed no-op feature was "active," unhedged, one line below a properly-hedged claim about a different feature — plus a crash fix in one of the dynamic-workflow scripts and two new regression tests written specifically to keep the godmode-removal and --minimal fixes from 11.9.9 from silently regressing. The MEDIUM/LOW list is the unglamorous kind of hardening that doesn't make headlines but is exactly what "ready for real users" should mean in practice: a missed curl-chmod-run dropper-chain pattern in the install-time security gate, a prototype-pollution guard added to a shared config singleton, a CodeQL-flagged regex-escape bug, a non-LTS base image reverted, a persona-table doc regenerated wholesale from source instead of hand-maintained, and a release-pipeline step that had been silently failing on four consecutive prior releases for a root-caused, now-fixed reason.

So, the honest final answer to what this release means: a mature, iteratively-hardened orchestration layer, now on its 77th npm publish, just finished a second full external-readiness audit, found and fixed one more real critical bug in the process, and shipped — tagged, published, live — as exactly what its own CHANGELOG calls itself: the first release cut deliberately for real external users, not just internal iteration. That's a more credible launch story than an inflated "v1.0" narrative would ever be, precisely because the discipline of catching real bugs before shipping to real users kept recurring right up to the moment this one actually went out the door.