Gene Lifecycle Commands

rotifer init

Initialize a new Rotifer project with Genesis genes and Arena preview.

rotifer init [project-name]

Arguments:

Argument	Required	Description
project-name	No	Directory name (defaults to my-rotifer-project)

Options:

Flag	Description
--domain <domain>	Default gene domain (default: general)
--fidelity <level>	Example gene fidelity: Wrapped | Hybrid | Native (default: Wrapped)
--no-genesis	Skip genesis genes installation

What it creates:

my-project/
├── rotifer.json          # Project configuration
├── genes/                # Gene source directory
│   ├── genesis-web-search/
│   ├── genesis-web-search-lite/
│   ├── genesis-file-read/
│   ├── genesis-code-format/
│   └── genesis-l0-constraint/
└── .rotifer/
    └── playground.db     # Local Arena database

Example:

$ rotifer init my-project
✨ Project initialized at ./my-project

$ cd my-project && rotifer arena list
# Shows Genesis genes pre-ranked in the local Arena

---

rotifer scan

Scan source files for candidate functions that can be wrapped as genes.

rotifer scan [path]

Arguments:

Argument	Required	Description
path	No	Path to scan (defaults to .)

Options:

Flag	Description
--skills	Scan for SKILL.md files instead of source functions
--skills-path <dir>	When using --skills, directory to scan (default: [path] or .cursor/skills)

Supported languages: TypeScript (.ts, .js), Rust (.rs)

Detection patterns:

• export function name()
• export async function name()
• export const name =
• pub fn name() / pub async fn name()

Example:

$ rotifer scan src/tools/
  Scanning src/tools/search.ts...

  Found 3 candidate functions:
  ┌────┬──────────────┬──────────────────────┬──────┐
  │ #  │ Name         │ File                 │ Line │
  ├────┼──────────────┼──────────────────────┼──────┤
  │ 1  │ webSearch    │ src/tools/search.ts  │ 12   │
  │ 2  │ fileRead     │ src/tools/file.ts    │ 8    │
  │ 3  │ codeFormat   │ src/tools/format.ts  │ 5    │
  └────┴──────────────┴──────────────────────┴──────┘

---

rotifer wrap

Wrap a function as a Rotifer gene, generating a Phenotype and shim code.

rotifer wrap <gene-name> --domain <domain> [options]

Arguments:

Argument	Required	Description
name	Yes	Gene name

Options:

Flag	Description
-d, --domain <domain>	Functional domain (e.g., search.web, file.read)
--fidelity <level>	Fidelity level (default: Wrapped)
--from-skill <path>	Create gene from a SKILL.md file (path to SKILL.md or its directory)
--from-clawhub <slug>	Create gene from a ClawHub skill (downloads and converts automatically)

Generated files:

genes/<name>/
├── phenotype.json    # Gene metadata (domain, schemas, fidelity)
├── index.ts          # Express function wrapper
└── shim.ts           # Compatibility shim

Example:

$ rotifer wrap my-search --domain search.web
  ✓ Gene 'my-search' wrapped successfully

  Domain:   search.web
  Fidelity: Wrapped
  Version:  0.1.0

---

rotifer test

Execute sandbox tests against a gene, validating schemas and behavior.

rotifer test <gene-name> [options]

Arguments:

Argument	Required	Description
name	Yes	Gene name to test

Options:

Flag	Description
--verbose	Show detailed input/output for each test case
--compliance	Run structural compliance checks (sandbox, L0, fuel metering, IR integrity)

Test cases run automatically:

1. Schema validation — Phenotype conforms to Gene Standard
2. Express function — express() is exported and callable
3. Input/Output conformance — Output matches outputSchema
4. Error handling — Graceful failure on invalid input
5. Null check — express() returns non-null data
6. Sandbox execution — Compiled genes execute through WASM sandbox; uncompiled genes fall back to Node.js with a warning
7. IR verification — WASM module contains all required custom sections

With --compliance, 6 additional structural checks run:

• C1: Sandbox execution verification (sandbox_type == “wasm”)
• C2: Fuel consumption verification (fuel_consumed > 0)
• C3: L0Gate pre-execution check pass
• C4: Phenotype field completeness (Gene Standard)
• C5: F(g) computability (all input metrics available)
• C6: IR segment integrity (custom WASM sections)

Example:

$ rotifer test my-search
  Running tests for 'my-search'...

  ✓ Phenotype schema is valid
  ✓ express() returned successfully
  ✓ Output conforms to outputSchema
  ✓ Error handling works correctly

  All 4 tests passed ✓
  Fitness: F(g) = 0.8234  V(g) = 0.9100

---

rotifer compile

Compile a gene to Rotifer IR (WASM with custom sections).

rotifer compile [gene-name] [options]

Arguments:

Argument	Required	Description
gene-name	No	Gene name (auto-detects if omitted)

Options:

Flag	Description
--check	Validate only, don’t produce artifacts
--wasm <path>	Path to pre-compiled .wasm file to wrap as IR
--lang <ts|wasm>	Force compilation mode (auto-detected by default)

Compilation pipeline:

TypeScript source
    ↓ esbuild (bundle + minify)
WASI-compatible JavaScript
    ↓ IR compiler (QuickJS → WASM)
Raw WASM module
    ↓ Rotifer IR Injector
gene.ir.wasm (with custom sections)

Custom sections injected:

• rotifer.version — Protocol version
• rotifer.phenotype — Serialized phenotype
• rotifer.constraints — L0 constraint metadata
• rotifer.metering — Fuel/resource limits

Example:

$ rotifer compile my-search
  Compiling 'my-search'...

  Pipeline: TypeScript → esbuild → IR compiler → IR
  ✓ Compiled successfully

  IR Hash:  a3f2b1...c4d5
  Size:     142.3 KB
  Sections: version, phenotype, constraints, metering

Output: genes/<name>/gene.ir.wasm