MindForge

Multi-agent AI workflows are powerful but chaotic: unbounded token spend, logic drift in long loops, and no audit trail. MindForge is a command-driven orchestration framework for Claude Code that brings governance to that chaos.

It exposes 174 slash commands, 154 specialized subagents, and 73 skills plus a hooks system, cost-aware model routing (Haiku/Sonnet/Opus tier escalation), SHA-256 audit chains, and stuck-detection with auto-repair. Execution runs on a semaphore-based wave (parallel) model with a streaming WebSocket SDK, persisted through an embedded sql.js datastore. Ships as npx mindforge-cc.

• 174 commands · 154 subagents · 73 skills
• Wave parallelism via a DAG + dependency tracking
• Cost-aware routing + audit/replay via hash-linked logs
• Built on a pure Node.js + WASM runtime with a strict-TypeScript SDK

1,677 commits — the most-invested project in the portfolio.

Architecture

MindForge splits into four load-bearing subsystems. Wave execution (bin/autonomous/wave-executor.js + bin/autonomous/dependency-dag.js) topologically sorts tasks with Kahn's algorithm, detects cycles explicitly, and groups the result into waves bounded by a hand-rolled Semaphore. Model routing (bin/models/model-router.js) maps personas to model tiers — planner and security personas escalate to Opus, executor/reviewer/QA run on Sonnet, quick tasks run on Haiku — configurable via MINDFORGE.md; a separate difficulty-scorer.js computes a per-task difficulty score but runs in shadow mode, logging intended routing to stderr without touching the real model call. Governance (bin/governance/audit-hash.js + audit-verifier.js, paired with bin/autonomous/audit-writer.js) is a single canonical SHA-256 hasher shared by the writer and the verifier, chaining each audit entry to the one before it. Persistence splits in two: resumable session state (tasks, waves, audit pointers) lives in .planning/HANDOFF.json via bin/autonomous/state-manager.js, while a separate embedded sql.js (WASM SQLite) datastore (celestial.db) holds traces, remediations, skills, and knowledge — not task/wave resumability. Streaming is a WebSocket SDK (sdk/src/events.ts) that ships with zero runtime dependencies.

How It Works

1. A task enters the engine and dependency-dag.js builds a DAG from its declared dependencies, topologically sorting it into waves — a circular dependency throws immediately instead of deadlocking silently.
2. Within a wave, wave-executor.js's Semaphore bounds how many tasks run concurrently, so parallelism is real but capped.
3. Each task resolves its model tier through model-router.js's persona map; when a caller passes a taskContext, difficulty-scorer.js also runs in shadow mode, computing what would route differently but never overriding the persona map's actual choice.
4. As work completes, bin/autonomous/audit-writer.js appends an entry to the local audit log, hashing it against the previous entry's hash via bin/governance/audit-hash.js — a tamper-evident chain, though the log itself (.planning/AUDIT.jsonl) is gitignored, so it protects a local run rather than git history.
5. State — tasks, waves, audit pointers — persists to .planning/HANDOFF.json via state-manager.js, so a session can resume after a crash.
6. Progress and results stream out over WebSocketEventStream to any connected SDK client; verify-audit.js can independently replay the chain and fails closed the moment a hash breaks.