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:

bash

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:

json

{
  "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:

#Capability unitDomainInputOutput1Grammar checkcontent.grammartextissues[], score2Readability analysiscontent.readabilitytextgrade, suggestions[]

---

Phase 2: Gene Selection#

Match existing Genes to each capability unit.

bash

rotifer list                                  # what is already in this workspace
rotifer arena list --domain <domain>          # ranked by F(g) within one domain
rotifer search <capability> --domain <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:

PrioritySourceCommand1Local Gene with highest Arena rankrotifer arena list --domain <d>2Cloud Registryrotifer search <capability> → rotifer info <ref> → rotifer install <ref>3Doesn't exist, needs creationProceed to Phase 3

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:

bash

rotifer run <gene-name> --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:

ApproachWhen to useActionCreate Wrapped GeneExternal API / Skill available to wrapRoute to gene Skill (dev module)Create Native GenePure computation, no external dependenciesRoute to gene Skill (dev module)Adjust decompositionCapability unit granularity is wrongReturn to Phase 1Merge unitsTwo units are too coupled, splitting makes the interface awkwardMerge into one 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#

StrategySemanticsUse whenExample**Seq(A, B, C)Pipeline: A → B → CPrevious output feeds the nextCheck → Fix → FormatPar(A, B)Parallel: run simultaneouslyIndependent tasks, merge resultsGrammar check + Readability analysisCond(p, A, B)Branch: if p then A else BInput characteristics determine pathChinese → Chinese proofing / English → English proofingTry(A, B)Fallback: A fails → BPrimary path unreliableMain API → Backup APITryPool(A, B, C)**Race: all try, first success winsMultiple equivalent implementationsMultiple translation services racing

Par Merge Strategies#

When using Par, specify --par-merge:

StrategyBehaviorUse whenfirstTake the first completed resultRacing scenarioconcatConcatenate all results (array)Results are complementarymergeDeep-merge objectsSame structure, merge fields

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:

text

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

Corresponding CLI:

bash

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/<id>.json.

---

Phase 5: Agent Creation#

Execute creation after confirming the composition plan.

Manual Gene Selection#

bash

rotifer agent create <name> \
  --genes <gene1> <gene2> <gene3> \
  --composition <Seq|Par|Cond|Try|TryPool> \
  --par-merge <first|concat|merge>

Auto-select Genes (by domain ranking)#

bash

rotifer agent create <name> \
  --domain <domain> \
  --top <n> \
  --composition <strategy>

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

---

Phase 6: Test Run#

bash

rotifer agent list
rotifer agent run <name> --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#

ProblemOptimizationOne Gene's output quality is poorrotifer arena list --domain <d> for ranked local alternatives, or rotifer search <capability> to look beyond what is installedNot sure which Gene in the pipeline is at faultrotifer run <gene-name> --input '{...}' on each one in isolationSeq intermediate results missing fieldsCheck schema compatibility, consider inserting an adapter GenePar merge results are messySwitch --par-merge strategyLatency too highSeq → Par (if Genes are independent)Overall below expectationsRoute to rotifer-arena Skill for head-to-head Gene evaluation

---

Scenario Examples#

Scenario 1: Document Quality Agent#

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

Decomposition:

#CapabilityGeneDomain1Grammar checkgrammar-checkercontent.grammar2Readability analysisreadability-analyzercontent.readability3Tone analysistone-analyzercontent.tone

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

bash

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.

#CapabilityGeneDomain1Security auditsecurity-auditorsecurity.audit2Complexity analysiscode-complexitycode.analysis3Documentation generationdocs-writercontent.docs

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

bash

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.

#CapabilityGeneDomain1Web searchgenesis-web-searchsearch.web2Text summarizationtext-summarizercontent.summarize3Markdown formattingmarkdown-formattercontent.format

Composition: Strict serial pipeline → Seq.

bash

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.

RunsThe rotifer CLI ( @rotifer/playground), fetched from npm if not installed.ReadsGenes and Agent definitions in the current project workspace.WritesOnly what the commands below write — Genes into the project's genes/, Agent definitions into .rotifer/agents/. Nothing outside the project.SendsCloud registry and Arena queries, to the public Rotifer API. Your code is not uploaded unless you run rotifer publish yourself.

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

---

Related Skills#

SkillRelationshipWhen to routegene (dev module)Gene creation/developmentPhase 3 gap fillingrotifer-arenaGene comparison & evaluationPhase 7 when replacing underperforming GenesgenomeGenome quality analysisAfter Agent creation for overall assessment

---

Constraints#

• Agent configuration files are stored in .rotifer/agents/<id>.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