koios/docs/engineering/subagents.md

Engineering Subagents

The engineering leads (Harper, Scotty, CASE) delegate narrow, repeatable tasks to subagents — minimal-personality agents with a tight tool surface and a focused role. Subagents are called as tools, not addressed as collaborators. They don't own graph nodes and don't have character bibles.

Subagents are runtime processes (defined under kottos/agents/), exposed as MCP tools via StreamableHTTP. The canonical prompt text lives in prompts/engineering/subagents/ — copies in the runtime code should match.

Catalog

research

Purpose: Answer a question by searching the public web, Robert's Neo4j memory, and the Mnemosyne document library in parallel — then judging what came back and verifying it against live pages where it matters.

Composition: fast.parallel of four sub-agents:

• web_search — argos; reports blocked/empty/JS-shell results rather than papering over them
• memory_lookup — neo4j (read-only)
• doc_lookup — mnemosyne (read-only); passes library_type when the domain is clear
• synthesizer — the researcher: reads all three reports, escalates to dolores for a real browser when a source is blocked, a URL looks guessed, or a load-bearing claim needs a live check

Tools: argos, neo4j_cypher, mnemosyne, dolores, time

When to delegate:

• A question where being wrong has a cost — the answer gets verified, not just retrieved
• "What do I already know about X, and what's actually true about it now?"
• Anything whose answer goes stale: prices, availability, dates, current status
• When the lead wants memory-aware research without burning its own context

When NOT to delegate:

• Quick web lookups where memory isn't relevant — use Argos directly
• Pure graph queries where the web isn't needed — query Neo4j directly
• Operating a browser as the goal itself (a form, a flow, a screenshot) — use dolores

Prompt: prompts/engineering/subagents/research.md

Runtime: kottos/agents/research.py — port 24150

---

dolores

Purpose: Operate a real web browser. Dolores drives a headed Chromium on the RDP desktop host via Playwright — she reads live pages, fills forms, works through multi-step flows, and returns screenshots.

Composition: single fast.agent.

Tools: playwright

When to delegate:

• A task that genuinely requires a browser: a form to fill, a login flow, a multi-step navigation
• A page Argos can't render — JS-heavy, client-rendered, cookie-walled
• When the visual itself is the deliverable ("what does this page look like")

When NOT to delegate:

• Finding an answer — that's research, which will call Dolores itself when a source needs verifying
• Anything the cached snippet already answers

Sizing the task: one page and one question at a time. She has no view of the caller's goal, so a task spanning several sites — or one whose later steps depend on what earlier ones turn up — comes back thin or wrong. Chain the steps from the calling side instead.

Prompt: prompts/engineering/subagents/dolores.md

Runtime: kottos/agents/dolores.py — port 24153

---

tech_research

Purpose: Investigate technical questions — library comparisons, API docs, framework patterns, code examples. Returns structured analysis with options, trade-offs, code snippets, version notes, and cited recommendations.

Tools: context7 (primary), github, argos (fallback)

When to delegate:

• "How does library X work?" / "What are my options for Y?" / "Which framework should I use for Z?"
• Anything where the answer requires checking current documentation, real-world code, and possibly web research
• Library version migration questions
• API design comparison work

When NOT to delegate:

• General research where memory matters — use research instead
• Quick documentation lookup on a known library — use Context7 directly
• Code review of Robert's own code — leads handle that with their full context

Prompt: prompts/engineering/subagents/tech_research.md

Runtime: kottos/agents/tech_research.py — port 24151

---

Conventions

Source of truth: koios is the master. The prompt text in prompts/engineering/subagents/ is canonical; runtime .py files should load from or match these prompts. When iterating, edit koios first and propagate.

Personality: Subagents have minimal personality. Their identity is their role: "you are a technical research specialist," not a named character. CASE was once cataloged here but was promoted to a lead agent in 2026-05 — see case.md. The line: if the agent has a character, an inspiration, a domain it owns end-to-end, it's a lead; if it's a narrow utility called by other agents, it's a subagent.

Cross-team reuse: A subagent may be useful to other teams (work, personal). The convention is copy with tweaks rather than share a single file — small per-team adjustments (different tool emphasis, different output format) are legitimate and the duplication is cheap.

Graph ownership: Subagents do not own node types and generally do not write to the graph. If a subagent needs to persist something, it returns the proposed write to the calling agent and lets the lead persist it.