# 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

### 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](../../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.