koios/docs/work/subagents.md

Work Subagents

The work leads (Alan, Ann, Jeffrey, Jarvis, Quentin) 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. Quentin drives the architecture-focused subagents (aws-sa exclusively, plus tech_research).

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 — use the work-team tech_research subagent (below).

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

Driven by: Quentin (exclusive). AWS architecture requests from other work leads route to Quentin, who delegates to aws-sa. Demo-scoped — demo-scale designs only, no production accounts/data/hardening; production architecture routes to Scotty via Quentin.

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

---

tech_research

Driven by: Quentin primarily (technical investigation feeding solution design and demos), available to any work lead.

Purpose: Investigate technical questions — library/framework/API comparisons, documentation, real-world code examples — and return structured analysis with cited recommendations.

Composition: Single fast.agent. Checks context7 (official docs) → github (real-world code) → argos (web fallback), adapting order to the query.

Tools: context7 (primary), github, argos

When to delegate:

• Library/framework/API comparison for a solution's stack or a demo (non-AWS technical depth)
• "What's the current best way to do X with library Y?" with version-compatibility notes
• Documentation and real-world code examples to ground a design decision

When NOT to delegate:

• AWS architecture questions — use aws-sa (it has the AWS knowledge/docs/pricing servers)
• Quick tactical web checks — use argos directly
• Memory-aware research blending the graph and the public web — use research

Note: Work-team copy of engineering's tech_research, per the cross-team-reuse convention (copy with tweaks, don't share a file). The prompt is domain-neutral, so the copy is near-identical.

Prompt: prompts/work/subagents/tech_research.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.