docs: add Athena CRM documentation and update Alan persona reference
- New docs/tools/athena.md documenting CRM capabilities and MCP tools - Refactor docs/work/alan.md to separate system prompt from persona reference - Clarify Athena scope, vocabulary, and operational gotchas
This commit is contained in:
43
docs/work/subagents.md
Normal file
43
docs/work/subagents.md
Normal file
@@ -0,0 +1,43 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user