rotifer-agent

Build a Rotifer Agent from Genes — decompose intent into capability units, pick Genes by Arena F(g), compose a Rotifer Genome, create the Agent and test it. Use when the user is working with Rotifer specifically: "Rotifer Agent", "compose Genes", "Rotifer Genome", "Gene composition", "rotifer agent create". Do NOT use for general agent frameworks, or when the words Seq / Par / Cond / Try appear as ordinary programming terms — in Rotifer those name Genome composition strategies, and this Skill applies only when the user is composing Rotifer Genes.

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 unit	Domain	Input	Output
1	Grammar check	content.grammar	text	issues[], score
2	Readability analysis	content.readability	text	grade, 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:

Priority	Source	Command
1	Local Gene with highest Arena rank	rotifer arena list --domain <d>
2	Cloud Registry	rotifer search <capability> → rotifer info <ref> → rotifer install <ref>
3	Doesn't exist, needs creation	Proceed 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:

Approach	When to use	Action
Create Wrapped Gene	External API / Skill available to wrap	Route to gene Skill (dev module)
Create Native Gene	Pure computation, no external dependencies	Route to gene Skill (dev module)
Adjust decomposition	Capability unit granularity is wrong	Return to Phase 1
Merge units	Two units are too coupled, splitting makes the interface awkward	Merge 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

Strategy	Semantics	Use when	Example
Seq(A, B, C)	Pipeline: A → B → C	Previous output feeds the next	Check → Fix → Format
Par(A, B)	Parallel: run simultaneously	Independent tasks, merge results	Grammar check + Readability analysis
Cond(p, A, B)	Branch: if p then A else B	Input characteristics determine path	Chinese → Chinese proofing / English → English proofing
Try(A, B)	Fallback: A fails → B	Primary path unreliable	Main API → Backup API
TryPool(A, B, C)	Race: all try, first success wins	Multiple equivalent implementations	Multiple translation services racing

Par Merge Strategies

When using Par, specify --par-merge:

Strategy	Behavior	Use when
first	Take the first completed result	Racing scenario
concat	Concatenate all results (array)	Results are complementary
merge	Deep-merge objects	Same 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

Problem	Optimization
One Gene's output quality is poor	rotifer arena list --domain <d> for ranked local alternatives, or rotifer search <capability> to look beyond what is installed
Not sure which Gene in the pipeline is at fault	rotifer run <gene-name> --input '{...}' on each one in isolation
Seq intermediate results missing fields	Check schema compatibility, consider inserting an adapter Gene
Par merge results are messy	Switch --par-merge strategy
Latency too high	Seq → Par (if Genes are independent)
Overall below expectations	Route 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:

#	Capability	Gene	Domain
1	Grammar check	grammar-checker	content.grammar
2	Readability analysis	readability-analyzer	content.readability
3	Tone analysis	tone-analyzer	content.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.

#	Capability	Gene	Domain
1	Security audit	security-auditor	security.audit
2	Complexity analysis	code-complexity	code.analysis
3	Documentation generation	docs-writer	content.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.

#	Capability	Gene	Domain
1	Web search	genesis-web-search	search.web
2	Text summarization	text-summarizer	content.summarize
3	Markdown formatting	markdown-formatter	content.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.

Runs	The rotifer CLI (@rotifer/playground), fetched from npm if not installed.
Reads	Genes and Agent definitions in the current project workspace.
Writes	Only what the commands below write — Genes into the project's genes/, Agent definitions into .rotifer/agents/. Nothing outside the project.
Sends	Cloud 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

Skill	Relationship	When to route
gene (dev module)	Gene creation/development	Phase 3 gap filling
rotifer-arena	Gene comparison & evaluation	Phase 7 when replacing underperforming Genes
genome	Genome quality analysis	After 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