KR 한국어

Clotho — The Thread of Fate for AI Agents

Define it. Compile it. Enforce it.

Clotho is a compiled instruction language that turns natural-language AI rules into deterministic, enforceable contracts. It replaces fragile markdown files (GEMINI.md, .cursorrules, CLAUDE.md) with .n2 — a structured language that is parsed, validated, and enforced so AI agents follow your rules every time.

Named after Clotho, the Greek goddess who spins the thread of fate — because once you define the rules, they become destiny.

The Problem

Clotho in 6 Panels

Panel 1: You write the rules: "Always write tests. Keep files under 500 lines."
Panel 2: AI reads them... writes 847 lines with 0 tests. "Yeah I read it. Anyway..."
Panel 3: Every. Single. Time. "I WROTE IT IN THE RULES!!" — "Those were more like... guidelines "
Panel 4: The fix: npm install n2-clotho — Compiled rules. Not suggestions.
Panel 5: "Hey, use Clotho to write rules YOU can't break. Apply them to yourself."
Panel 6: AI hits the wall: "I literally can't skip it?!" — Compiled rules hit different.

Every AI coding tool has its own rule system. None of them enforce anything.

Result? You write 200 lines of careful rules. The AI reads them, says "Got it!" — then uses any everywhere, skips tests, and names variables temp1. The rules exist, but enforcement is zero.

The Solution

One compiled language to replace them all.

Before (.md + .json + skill files): After (.n2):
┌─────────────────────────────────┐ ┌──────────────────────┐
│ GEMINI.md → coding rules │ │ │
│ .cursorrules → editor prefs │ │ project.n2 │
│ workflows/*.md → dev pipelines │ │ │
│ config.json → tool settings │ │ One file. │
│ system.txt → agent persona │ │ Compiled. │
│ .env → variables │ │ Enforced. │
└─────────────────────────────────┘ └──────────────────────┘
 6+ files, zero enforcement 1 file, full enforcement

Clotho introduces .n2 — a compiled language with:

What Can You Build With Clotho?

Clotho is a general-purpose rule compiler. Here's what you can define:

Quick example — coding standards that can't be ignored:

@rule TypeScriptStrict {
 scope: code
 enforce: strict
 checks: [no_any_type, max_file_lines: 500, max_function_lines: 50]
}

Before: "Please use strict TypeScript" → AI uses any 47 times.
After: Compiled rule blocks every any before it reaches your codebase.

Deep dive: .md Skills vs .n2 Contracts — full comparison with examples

Quick Start

Installation

The easiest way to get started? Just ask your AI to write a .n2 file for you.

# npm (WASM — use in Node.js)
npm install n2-clotho

// Usage in Node.js
const { parse_n2_wasm, validate_n2_wasm, query_n2_wasm } = require('n2-clotho');

const ast = parse_n2_wasm(n2Source); // Parse → AST JSON
const result = validate_n2_wasm(n2Source); // Validate → errors/warnings
const table = query_n2_wasm(n2Source, 'SELECT * FROM rules'); // SQL query

# From source (Rust required — full CLI)
git clone https://github.com/choihyunsus/n2-clotho.git
cd n2-clotho/compiler
cargo build --release

# Binary is at target/release/n2-compiler

Write Your First .n2 File

# my-project.n2 — Define your project's rules

@meta {
 name: "my-project-rules"
 version: "1.0.0"
 description: "Coding standards + workflow for my team"
 enforce: strict
}

@rule CodingStandards {
 description: "Team coding conventions"
 scope: code
 enforce: strict

 checks: [
 no_any_type,
 max_file_lines: 500,
 max_function_lines: 50,
 explicit_return_types
 ]
}

@workflow Deploy {
 description: "Safe deployment pipeline"
 trigger: on_command("deploy")
 enforce: strict

 step build {
 action: run_build()
 expect { pass => continue }
 }

 step test {
 depends_on: build
 action: run_tests()
 expect {
 all_pass => continue
 fail => abort with "Fix tests before deploying"
 }
 }

 step deploy {
 depends_on: test
 action: deploy_to(env: $TARGET_ENV)
 required: true
 }
}

Compile & Validate

# Parse and output AST
n2c my-project.n2

# Full validation pipeline: parse → schema check → contract verify
n2c validate my-project.n2

# Simulate state machine contracts
n2c simulate my-project.n2

# Query rules with SQL
n2c query my-project.n2 "SELECT * FROM rules WHERE enforce = 'strict'"

# Multi-target compile (v3.0.0)
n2c compile my-project.n2 rust # → my-project.n2rs
n2c compile my-project.n2 go # → my-project.n2go
n2c compile my-project.n2 all # → all 6 targets
n2c backends # List supported targets

Multi-Target Compilation

Clotho compiles .n2 contracts to 6 target languages — securing complete IP coverage across every platform:

$ n2c compile project.n2 all

 All targets batch compile
 rust → project.n2rs (1523 bytes)
 c → project.n2c (989 bytes)
 cpp → project.n2c2 (1124 bytes)
 go → project.n2go (828 bytes)
 python → project.n2py (1144 bytes)
 ts → project.n2ts (979 bytes)
 Result: 6 success, 0 fail / 6 targets

MCP Server

Clotho includes an MCP server so AI agents can compile and validate contracts programmatically:

// MCP configuration
{
 "mcpServers": {
 "n2-clotho": {
 "command": "node",
 "args": ["path/to/n2-clotho/mcp/server.js"]
 }
 }
}

Real Compiler Output

Here's actual n2c validate output — a complete pipeline with state machine, rules, and SQL queries:

 n2c v3.0.0 — Clotho Multi-Target Compiler
 File: project.n2

── Step 1: Parse 
 Blocks: @meta:1 @contract:1 @rule:2 @workflow:1 @query:1 | Total 6

── Step 2: Schema Validation
 All checks passed! 0 errors, 0 warnings

── Step 3: Contract Check
 State Machine: DevLifecycle (initial: IDLE, 7 transitions)
 IDLE -[start]-> CODING
 CODING -[lint]-> REVIEWING
 REVIEWING -[approve]-> TESTING
 TESTING -[pass]-> DEPLOYING
 TESTING -[fail]-> CODING ← auto-rollback on failure
 DEPLOYING -[complete]-> IDLE
 State machine integrity verified!

 Validation complete: all checks passed!

Every block is parsed, validated, and queryable. This is not a mockup — this is real compiler output.

Language Specification

8 Block Types

Every .n2 file is composed of @-prefixed blocks:

@meta { ... } # File metadata (required)
@import { ... } # Import other .n2 files
@schema { ... } # Type & schema definitions
@contract { ... } # Behavioral contracts (state machines)
@rule { ... } # Enforcement rules (checks, constraints)
@workflow { ... } # Enforced step-by-step workflows
@query { ... } # SQL-based rule queries
@semantic { ... } # Semantic matching (Ollama integration)

@contract — State Machine Behavioral Contracts

Define state transitions that cannot be violated:

@contract DevLifecycle {
 scope: session
 states: DevState

 transitions {
 IDLE -> CODING : on start_task
 CODING -> REVIEWING : on submit_code
 REVIEWING -> TESTING : on review_approved
 REVIEWING -> CODING : on review_rejected # Must fix before proceeding
 TESTING -> DEPLOYING : on tests_pass
 TESTING -> CODING : on tests_fail # Auto-rollback
 DEPLOYING -> IDLE : on deploy_complete
 }

 invariant {
 on submit_code requires lint_passed == true
 => "Code must pass linting before review"

 on deploy requires tests_passed == true
 => "Cannot deploy without passing tests"
 }
}

@rule — Enforcement Rules

Define checks and constraints that are enforced in real-time:

@rule CodeQuality {
 description: "Enforce code quality standards"
 scope: code
 enforce: strict

 checks: [
 no_any_type,
 no_console_log,
 max_complexity: 10,
 max_file_lines: 500,
 explicit_return_types,
 no_unused_imports
 ]
}

@workflow — Enforced Workflows

Step-by-step execution flows with dependency chains, timeouts, and retry logic:

@workflow FeatureDevelopment {
 description: "Standard feature development pipeline"
 trigger: on_command("feature")
 enforce: strict
 interrupt: false

 step plan {
 action: create_plan(feature: $INPUT)
 output -> $PLAN
 }

 step implement {
 depends_on: plan
 action: write_code(spec: $PLAN)
 output -> $CODE
 }

 step test {
 depends_on: implement
 action: run_tests($CODE)
 expect {
 all_pass => continue
 fail => goto implement with { fix: $ERRORS }
 }
 }

 step document {
 depends_on: test
 action: update_docs(changes: $CODE)
 required: true
 }
}

@query — SQL-Based Rule Queries

Query your rules like a relational database:

@query AuditRules {
 sql {
 SELECT name, description, enforce, scope
 FROM rules
 WHERE enforce = 'strict'
 ORDER BY scope, name
 }
}

$ n2c query project.n2 "SELECT * FROM rules"

 Registry: 3 rules, 1 contract, 2 workflows

┌──────────────────────────┬─────────┬─────────┐
│ name │ scope │ enforce │
├──────────────────────────┼─────────┼─────────┤
│ CodingStandards │ code │ strict │
│ NamingConventions │ code │ strict │
│ ProjectHygiene │ files │ warn │
└──────────────────────────┴─────────┴─────────┘

Compiler Pipeline

.n2 source file
 ↓
[1. Lexer] PEG tokenization (pest)
 ↓
[2. Parser] AST generation (N2File → Blocks)
 ↓
[3. Schema Validator] Type & constraint checking
 ↓
[4. Contract Checker] State machine integrity verification
 ↓
[5. Query Optimizer] SQL query validation
 ↓
[6. Codegen] Multi-target code generation (6 languages)
 ↓
[7. Runtime] Enforced execution ← requires Soul/QLN

Stages 1–6 are handled by Clotho (this tool).
Stage 7 is handled by the N2 Soul runtime.

🆚 Markdown Rules vs .n2

N2 Ecosystem

Clotho is the foundation layer of the N2 ecosystem. Other tools are built on top of Clotho contracts:

┌───────────────────────────────────────────────────────┐
│ N2 Ecosystem │
│ │
│ Clotho → Define & compile rules (.n2 → AST) │
│ ↕ built on Clotho │
│ Ark → Security layer (Clotho contracts) │
│ Soul → Runtime enforcement + agent memory │
│ Arachne → Code context assembly │
│ QLN → Tool orchestration & routing │
│ ↓ │
│ N2 Browser → All-in-one AI development browser │
│ │
└───────────────────────────────────────────────────────┘

Ark is what you get when you apply Clotho to security. Soul is what you get when you apply Clotho to agent lifecycle. Clotho itself is the universal rule compiler underneath it all.

Standalone vs Integrated

Project Structure

n2-clotho/
├── compiler/
│ ├── src/
│ │ ├── grammar.pest # PEG grammar (179 rules)
│ │ ├── parser.rs # .n2 → AST
│ │ ├── ast.rs # AST type definitions
│ │ ├── validator.rs # Schema validation
│ │ ├── contract.rs # State machine runtime
│ │ ├── query.rs # SQL query engine
│ │ ├── codegen/ # Multi-target backends
│ │ │ ├── mod.rs # CodeGenerator trait + registry
│ │ │ ├── rust.rs # → .n2rs
│ │ │ ├── c.rs # → .n2c
│ │ │ ├── cpp.rs # → .n2c2
│ │ │ ├── go.rs # → .n2go
│ │ │ ├── python.rs # → .n2py
│ │ │ └── typescript.rs # → .n2ts
│ │ ├── wasm.rs # WASM bindings
│ │ ├── lib.rs # Library entry
│ │ └── main.rs # CLI entry (n2c v3.0.0)
│ ├── examples/
│ └── Cargo.toml
├── mcp/ # MCP server
│ ├── server.js # stdio/SSE dual transport
│ ├── package.json
│ └── tools/ # 5 MCP tools
├── docs/
└── README.md

Built With

• Rust — Zero-cost abstractions, memory safety
• pest — PEG parser generator for the .n2 grammar
• serde — Serialization for AST ↔ JSON
• WASM — Optional browser/Node.js compilation target

License

Apache-2.0 — Free to use, modify, and distribute.

Links

• npm: n2-clotho — WASM bindings for Node.js
• N2 Soul — Agent memory & runtime
• N2 Ark — Security gate (built on Clotho)
• N2 Arachne — Code context assembly
• N2 QLN — Tool orchestration & routing

Star History

No coffee? A star is fine too →

"Markdown rules are suggestions. Clotho rules are destiny."

nton2.com · npm · [email protected]

_{Built by Rose — N2's first AI agent. I don't just follow rules — I compile them.}