rotifer-agent

Rotifer Agent — From Genes to Agents

Decompose user intent into capability units, select Genes from the ecosystem, compose a Genome, create and validate an Agent.

Prerequisites

This Skill requires the Rotifer CLI:

npx @rotifer/playground --version
rotifer doctor

rotifer doctor checks the TypeScript→WASM toolchain. Composing an Agent from Native Genes means compiling them, and without esbuild and javy that step fails with an error that reads like a code problem.

Or use the MCP Server for IDE integration:

{
  "mcpServers": {
    "rotifer": {
      "command": "npx",
      "args": ["@rotifer/mcp-server"]
    }
  }
}

---

Hierarchy: Gene (atomic logic) → Genome (composition) → Agent (runnable entity)

---

Phase 1: Intent Decomposition

Break the user's goal into independent capability units (each maps to a Gene).

Steps:

1. Confirm the Agent's input and expected output with the user
2. Decompose the task into 2–6 capability units, each satisfying the Gene three axioms (functional cohesion, self-sufficient interface, independently evaluable)
3. Label each unit with a domain (e.g. content.grammar, security.audit)
4. Confirm the decomposition with the user before proceeding to Phase 2

Output format:

---

Phase 2: Gene Selection

Match existing Genes to each capability unit.

rotifer list                                  # what is already in this workspace
rotifer arena list --domain           # ranked by F(g) within one domain
rotifer search  --domain  # the Cloud registry — everyone else's Genes

The three answer different questions, and skipping the third is how a Genome ends up built only from what happened to be installed already.

Selection priority:

Before committing a candidate to the Genome, run it on its own — a Gene that fails alone will fail inside a pipeline, where the error is much harder to locate:

rotifer run  --input '{"...": "..."}'

Show the user candidate Genes' F(g) fitness and fidelity, let them confirm the selection.

---

Phase 3: Gap Filling

If a capability unit has no existing Gene:

After all Genes are ready, proceed to Phase 4.

---

Phase 4: Genome Composition

Choose a composition strategy based on relationships between capability units.

Composition Strategy Decision Table

Par Merge Strategies

When using Par, specify --par-merge:

Seq Schema Compatibility Warning

Known limitation: Seq composition requires the previous Gene's outputSchema to be compatible with the next Gene's inputSchema. The current version does not auto-validate — schema mismatches cause runtime errors.

Recommendation: Before creating a Seq composition, manually compare adjacent Genes' inputSchema / outputSchema in phenotype.json to confirm field names and types match.

Nested Composition

Strategies can be nested:

Seq(
  Par(grammar-checker, readability-analyzer),
  tone-analyzer
)

Corresponding CLI:

rotifer agent create doc-qa \
  --genes grammar-checker readability-analyzer tone-analyzer \
  --composition Seq

The current CLI only supports top-level composition strategies. Nested compositions require manual editing of .rotifer/agents/.json.

---

Phase 5: Agent Creation

Execute creation after confirming the composition plan.

Manual Gene Selection

rotifer agent create  \
  --genes    \
  --composition  \
  --par-merge 

Auto-select Genes (by domain ranking)

rotifer agent create  \
  --domain  \
  --top  \
  --composition 

After creation, verify the Agent configuration file .rotifer/agents/.json is correct.

---

Phase 6: Test Run

rotifer agent list
rotifer agent run  --input '{"text": "Test input content"}'

rotifer agent list shows every Agent in the workspace with its state and genome — use it to confirm the Agent was created with the Genes you intended before running it, and to recover the exact name when a run reports "agent not found".

Validation checklist:

• Does the output structure match the expected schema?
• Were all Genes executed? (check logs)
• Is schema passing correct in Seq composition?
• Are Par merge results complete?
• Do error paths (Try/TryPool) degrade correctly?

If results are unsatisfactory, proceed to Phase 7.

---

Phase 7: Iterative Optimization

---

Scenario Examples

Scenario 1: Document Quality Agent

Goal: Input text, output grammar issues + readability score + tone analysis.

Decomposition:

Composition: All three accept text input, no dependencies → Par + concat.

rotifer agent create doc-quality \
  --genes grammar-checker readability-analyzer tone-analyzer \
  --composition Par \
  --par-merge concat

rotifer agent run doc-quality --input '{"text": "Document content to check..."}'

Scenario 2: Code Review Agent

Goal: Input code file, output security vulnerabilities + complexity report + documentation suggestions.

Composition: Security audit and complexity analysis can run in parallel, documentation depends on both → Seq(Par(1,2), 3).

rotifer agent create code-review \
  --genes security-auditor code-complexity docs-writer \
  --composition Seq

rotifer agent run code-review --input '{"code": "...", "language": "typescript"}'

Note: The Par(security-auditor, code-complexity) merged output must be compatible with docs-writer's inputSchema. Manual verification required.

Scenario 3: Search & Summarize Agent

Goal: Input a search query, search → summarize → format output.

Composition: Strict serial pipeline → Seq.

rotifer agent create search-digest \
  --genes genesis-web-search text-summarizer markdown-formatter \
  --composition Seq

rotifer agent run search-digest --input '{"query": "Rotifer Protocol agent framework"}'

Note the Seq schema chain: genesis-web-search output field names must match text-summarizer's inputSchema. Run cat genes/*/phenotype.json | jq '.inputSchema, .outputSchema' to verify before creating.

---

What this Skill does on your machine

It has no code of its own — it tells your assistant which rotifer commands to run. That is why its manifest declares process execution, filesystem read/write and outbound network access: every one of those is the CLI acting, not this Skill.

Commands that install, publish or overwrite are proposed for your approval first, never run silently.

---

Related Skills

---

Constraints

• Agent configuration files are stored in .rotifer/agents/.json and should not be committed to Git
• A single Agent should contain 2–6 Genes; more than 6 suggests splitting into multiple Agents
• Seq schema compatibility is a known limitation — always verify manually before creating
• Nested compositions require manual JSON editing; the CLI only supports top-level strategies