Robert Helewka
fba4e4bb27
Canonical prompts had drifted from the deployed code. research gained a third
fan-out member (doc_lookup / mnemosyne) and its synthesizer was promoted from a
merge step into the researcher: it holds dolores and time, and escalates to a
real browser when a source comes back blocked, a URL looks guessed, or a
load-bearing claim needs a live check.
All three variants updated — personal, work, engineering — preserving each
team's memory framing and the personal variant's node-schema and Cypher
sections. The engineering variant was a near-stub; it now carries the same
structure as the others.
Dolores had no canonical prompt anywhere in koios despite running on all three
teams. Added prompts/{personal,work,engineering}/subagents/dolores.md from the
deployed instruction, unchanged — this closes a documentation gap rather than
altering her behaviour. Her prompt stays deliberately narrow: she is handed one
page and one question at a time, and browser tradecraft is what she is for.
docs/*/subagents.md gain a dolores entry with delegation guidance, including
the task-sizing rule that keeps callers from handing her multi-site errands.
Work's research Runtime line said "TBD, port to be assigned" — mentor's
research has been live on 24250 for some time.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
126 lines
8.1 KiB
Markdown
126 lines
8.1 KiB
Markdown
# 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 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/work/subagents/research.md](../../prompts/work/subagents/research.md)
|
|
|
|
**Runtime:** `mentor/agents/research.py` — port 24250
|
|
|
|
---
|
|
|
|
### 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/work/subagents/dolores.md](../../prompts/work/subagents/dolores.md)
|
|
|
|
**Runtime:** `mentor/agents/dolores.py` — port 24253
|
|
|
|
---
|
|
|
|
### 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](../../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](../../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.
|