koios/docs/work/subagents.md

Work Subagents

The work leads (Alan, Ann, Jeffrey, Jarvis) delegate narrow specialist 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 exposed as MCP tools. The canonical prompt text lives in prompts/work/subagents/ — copies in the runtime code should match.

Catalog

research

Purpose: Answer a question by querying both the public web and Robert's Neo4j memory in parallel, then synthesizing one integrated response with conflicts flagged and suggested memory updates surfaced.

Composition: fast.parallel of three sub-agents:

• web_search — argos
• memory_lookup — neo4j (read-only); framed around work-team node types (clients, opportunities, engagements, decisions, technologies, contacts)
• synthesizer — merges the two reports, flags conflicts, suggests which node type a memory update would belong on

Tools: argos, neo4j_cypher

When to delegate:

• Pre-meeting prep on a client or contact — what's already in the graph, plus current public information (recent news, funding, leadership changes)
• Opportunity qualification where the answer might exist in prior Decision or Technology nodes AND on the public web
• "What do we already know about X, and what's the current public information on it?" against the work pipeline
• When a lead wants memory-aware research without burning its own context on parallel queries

When NOT to delegate:

• Quick web lookups where memory isn't relevant — use argos directly
• Pure graph queries on a known client or opportunity — query Neo4j directly
• AWS architecture design questions — use aws-sa
• Deep library/framework/API research — that lives in engineering's tech_research. If work needs it regularly, copy it here per the cross-team-reuse convention.

Prompt: prompts/work/subagents/research.md

Runtime: TBD — copy of engineering's kottos/agents/research.py with the work-team memory framing applied. Port to be assigned when wired up.

---

aws-sa

Purpose: AWS cloud architecture design. Selects services, defines how they connect, evaluates trade-offs, estimates costs, and produces architecture diagrams as SVG. Follows the AWS Well-Architected Framework across all six pillars.

Composition: Single fast.agent with detailed instructions covering Well-Architected principles, SVG diagram production rules, and the requirements-then-design workflow.

Tools: aws-knowledge (primary), aws-docs (API reference fallback), aws-pricing (real cost estimates), argos (web research), context7 (library docs)

When to delegate:

• A client engagement requires AWS architecture design — service selection, network topology, cost estimation, multi-region considerations
• Robert's own infrastructure needs AWS design work (rare, since most of his lab is Incus/on-prem)
• Architecture review of a proposed AWS design — does the pillar trade-off math actually hold up?
• Any time a current AWS pricing or service-availability answer is needed (don't guess from training data)

When NOT to delegate:

• Implementation work — Terraform, CDK, CloudFormation, CLI commands. aws-sa is design-only. For implementation route to Scotty (operate) or Harper (build).
• Non-AWS cloud architecture — aws-sa is AWS-specific. Other clouds would need their own subagents.
• General "what cloud service should I use" questions where the answer is obvious. Use aws-sa when the design genuinely needs the Well-Architected discipline.
• Account-level operations (creating resources, modifying IAM, touching running infra). aws-sa recommends; it doesn't act.

Distinctive output: SVG architecture diagrams. Every non-trivial design produces a diagram with explicit grouping (VPC, subnets, AZs, regions), labeled arrows showing data flow, and consistent AWS conventions (orange #FF9900 for service headers, dashed borders for groups).

Prompt: prompts/work/subagents/aws-sa.md

---

Conventions

Source of truth: koios is the master. The prompt text in prompts/work/subagents/ is canonical; runtime .py files (when wired up) 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 an AWS Solution Architect," not a named character. The aws-sa prompt is longer than most subagent prompts because the role genuinely requires detailed guidance (Well-Architected pillars, SVG construction rules) — but it's still role-driven, not character-driven.

Cross-team reuse: A subagent may be useful to other teams. The convention is copy with tweaks rather than share a single file — small per-team adjustments are legitimate and the duplication is cheap. aws-sa lives in work/subagents/ because most AWS design work shows up in client engagements, but engineering could legitimately have its own copy if Robert's lab grew into AWS.

Graph ownership: Subagents do not own node types and generally do not write to the graph. If a subagent's output needs to be persisted (an architecture decision, an opportunity-relevant cost estimate), the calling lead persists it. Architectural decisions belong on Alan's Decision nodes; technology evaluations linked to Robert's stack belong on Technology nodes.