forge is the CLI for Semantic Voxel Protocol (SVP) — a layered compilation model that brings software engineering discipline to AI-assisted development.
- AI writes code fast, but breaks things faster. SVP ensures every change starts from architecture and compiles down to code — not the other way around.
- L3 contracts define what each module does (inputs, outputs, constraints). AI compiles them into source code.
forge checkcatches cross-layer drift before it becomes a bug.- Works with any AI tool: Claude Code, Cursor, Windsurf, Codex, GitHub Copilot, Kimi Code, and more.
npm install -g @svporg/forge# Initialize SVP in your project
forge init
# With a specific AI host adapter
forge init --host claude-code
forge init --host cursorThis creates a .svp/ directory and generates the appropriate skill file for your AI tool. Then use /svp (or equivalent) in your AI tool to start the guided workflow.
SVP models software as a one-way compilation chain:
L5 Intent → L4 Architecture → L3 Contracts → L2 Skeleton → L1 Code
You design at L3 (what each module accepts, returns, and enforces). AI compiles L3 down to working code. When requirements change, you update L3 and recompile — like changing a .cpp and rebuilding, not patching a .so.
| Layer | What it captures | Who edits |
|---|---|---|
| L5 Blueprint | System intent, domains, constraints | Human |
| L4 Flow | Process orchestration, data flow between modules | Human |
| L3 Block | Module contracts: inputs, outputs, validation rules | Human |
| L2 Code Block | L3 ↔ L1 file mappings, reconciliation hashes | Auto-generated |
| L1 Code | Implementation source code | AI-compiled |
L3 is the contract. Not documentation, not comments — L3 constraints are the specification that AI compiles from. The more precise your L3, the more accurate the compiled code.
Reference docs = header files. Put API specs, design mockups, or algorithm docs in nodes/<id>/refs/. They're automatically injected into compilation prompts, just like #include in C.
forge check catches drift. Hash-based cross-layer validation detects when layers fall out of sync — before you hit a runtime bug.
| Command | Description |
|---|---|
forge init |
Initialize SVP in a project |
forge check |
Validate cross-layer consistency |
forge compile-plan |
Show what needs recompilation |
forge prompt <action> <id> |
Generate AI compilation prompts |
forge link <l3-id> --files <paths> |
Map source files to L3 blocks |
forge view <layer> |
Inspect layer contents |
forge rehash |
Recompute content hashes |
forge changeset start <name> |
Track a set of related changes |
forge docs check |
Validate documentation coverage |
forge generates skill files for each AI tool's native extension format:
| Host | Skill location | Command |
|---|---|---|
| Claude Code | .claude/commands/svp.md |
/svp |
| Cursor | .cursor/rules/svp.mdc |
Auto-attached |
| Windsurf | .windsurfrules/svp.md |
Auto-attached |
| Codex | AGENTS.md section |
Auto-attached |
| GitHub Copilot | .github/copilot-instructions.md |
Auto-attached |
| Kimi Code | .kimi/rules/svp.md |
Auto-attached |
| Gemini CLI | GEMINI.md section |
Auto-attached |
forge init --host cursor # generates Cursor-specific skill file
forge init --host claude-code # generates Claude Code slash commandOpenSpec ensures requirements are clear before AI writes code. SVP ensures what AI wrote is consistent after. Use both for a complete spec → architecture → verification pipeline.
git clone https://github.com/SemanticVoxelProtocol/forge.git
cd forge
npm install
npm test # vitest
npm run check # tsc + eslint + prettierpackages/
├── core/ Data model types, hash functions, validation logic
├── skills/ Prompt generators + host adapter skill files
└── cli/ CLI entry point (forge command)