Robert Helewka
fefc9018ab
Two corrections. **1. Sophia was written from recall, not from the source.** Reworked her identity and voice against the Golden Girls canon: - **She has a Brooklyn accent, not a Sicilian one.** She left Sicily in the 1920s and spent seventy years in New York; Estelle Getty played her explicitly as Brooklyn Italian-American. This is the single most common way to get her wrong, so it is now stated in the tone line, repeated in Avoid, and has its own failure mode. - **"Picture it" is a parable, not a catchphrase.** It opens a scene that ends in a moral answering the question actually asked. The failure mode is using it as a verbal tic with no story behind it. - Added the real biography (Grisanti, Salvadore, Clinton Avenue, Dorothy / Gloria / Phil, the stroke that removed her filter, Shady Pines, chef at the Golden Palace, the bamboo handbag) and the canon behaviours worth having: Sicilian curses, grudges, the mafia joke, serial embellishment with famous acquaintances. - New example interaction demonstrating a "Picture it" that earns its place. **2. Agents no longer get told who they replaced.** Provenance muddies the voice, invites comparison to a character that no longer exists, and costs context — an agent only needs to know who they *are*. Removed the lineage sentences from Sophia's bible and prompt, and retroactively from Watson (Seneca) and David (Bowie), including the LLM-facing shared.md directory and the personal.md "Replaced agents" section. Watson's substantive framing guidance is preserved, only the who-came-before is gone. Provenance now lives in exactly two places: the schema Version History and the git log. New docs/roster-changes.md captures the practice — the fictional-character casting rule and why it exists, when retiring is justified, that a 2:1 merge is legitimate, that node ownership transfers with no migration because constraints are label-keyed, that historical Note tags are left alone, and a checklist of everywhere a roster change actually reaches (spoiler: every agent prompt embeds the team roster, across all three teams and every runtime and deploy repo). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
125 lines
7.1 KiB
Markdown
125 lines
7.1 KiB
Markdown
# Koios
|
|
|
|
> *Named for the Titan of intellect and the celestial axis around which the heavens revolve.*
|
|
|
|
System prompts, shared tools, and graph schema for Robert Helewka's AI assistants.
|
|
|
|
## Architecture
|
|
|
|
Each assistant's runtime prompt is composed from these layers:
|
|
|
|
| Layer | Location | Audience | Purpose |
|
|
|-------|----------|----------|---------|
|
|
| **System Prompt** | `prompts/{team}/{name}.md` | LLM | Identity, communication style, boundaries, graph domain (~400-600 words) |
|
|
| **Tool Prompt Snippets** | `prompts/tools/{tool}.md` | LLM | Per-tool usage discipline (e.g., "always check the `success` boolean") — composed into the system prompt to teach the model what MCP tool descriptions don't convey |
|
|
| **Shared Context** | `docs/tools/neo4j/shared.md` | LLM | MCP server inventory, Agathos sandbox map, inter-agent messaging protocol, assistant directory |
|
|
| **Graph Context** | `docs/tools/neo4j/{team}.md` | LLM | Team-specific Neo4j principles, node ownership, patterns |
|
|
|
|
Human reference documentation lives in `docs/`:
|
|
- `docs/{team}/{name}.md` — character design per assistant
|
|
- `docs/{team}/team.md` — team overview, responsibility matrix, handoff patterns
|
|
- `docs/{team}/subagents.md` — catalog of team-scoped subagents and when to delegate to them
|
|
- `docs/tools/{tool}.md` — per-tool reference (what it is, what it's good for, known gotchas)
|
|
- `docs/tools/neo4j/` — full graph schema, breaking changes, utility patterns
|
|
|
|
Subagents are minimal-personality utility agents called as tools by leads — see `docs/engineering/subagents.md` for the established pattern.
|
|
|
|
## Assistants
|
|
|
|
The lists below reflect what's currently in `prompts/{team}/` — the source of truth. When assistants are added, replaced, or retired, update the directory and these tables together.
|
|
|
|
**Assistants are fictional characters** — real people carry baggage that arrives with the name and can change after the fact, while a character has canon to write against. Adding, replacing, or retiring one touches far more files than it looks like (every agent prompt embeds the team roster) — see [docs/roster-changes.md](docs/roster-changes.md) for the practice and the checklist.
|
|
|
|
### Personal Team
|
|
| Assistant | Inspired By | Domain |
|
|
|-----------|------------|--------|
|
|
| **Shawn** | — | General assistant (calendar/contacts/email) |
|
|
| **Nate** | Nathan Drake | Travel & Adventure |
|
|
| **Hypatia** | Hypatia of Alexandria | Learning & Reading |
|
|
| **Marcus** | Marcus Aurelius | Fitness & Training |
|
|
| **Watson** | — | Relationship memory & emotional safety (replaces Seneca) |
|
|
| **Sophia** | Sophia Petrillo | Home, Food & Living Things (replaces Bourdain and Cousteau) |
|
|
| **David** | — | Arts & Culture (replaces Bowie) |
|
|
| **Garth** | Garth Turner | Personal Finance |
|
|
| **Cristiano** | Cristiano Ronaldo | Football |
|
|
|
|
### Work Team
|
|
| Assistant | Inspired By | Domain |
|
|
|-----------|------------|--------|
|
|
| **Alan** | Alan Weiss | Strategy & Positioning |
|
|
| **Ann** | Ann Handley | Content & Visibility |
|
|
| **Jeffrey** | Jeffrey Gitomer | Proposals & Sales |
|
|
| **Jarvis** | J.A.R.V.I.S. | Daily Execution |
|
|
| **Quentin** | Q (007 Quartermaster) | Solution architecture & demos |
|
|
|
|
Work subagents (called as tools, not lead agents): **AWS SA** (cloud architecture, Quentin's exclusive subagent) and **tech_research** (technical investigation). See [docs/work/subagents.md](docs/work/subagents.md).
|
|
|
|
### Engineering Team
|
|
| Assistant | Inspired By | Domain |
|
|
|-----------|------------|--------|
|
|
| **Harper** | Seamus Harper | Build — ideation through deployment |
|
|
| **Scotty** | Montgomery Scott | Operate — production ops & provisioning |
|
|
| **CASE** | CASE (Interstellar) | Field — physical layer, LAN, hardware |
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
koios/
|
|
├── prompts/ # Sent to LLM at runtime
|
|
│ ├── personal/ # Personal assistants (lead agents)
|
|
│ ├── work/ # Work assistants (lead agents)
|
|
│ │ └── subagents/ # Team-scoped subagents (aws-sa, research, tech_research)
|
|
│ ├── engineering/ # Engineering assistants (lead agents)
|
|
│ │ └── subagents/ # Team-scoped subagents (research, tech_research)
|
|
│ └── tools/ # Per-tool prompt snippets
|
|
│ ├── kernos.md # Shell/file-ops discipline
|
|
│ ├── argos.md # Web search
|
|
│ ├── mnemosyne.md # Multimodal KB
|
|
│ ├── grafana.md # Metrics + logs
|
|
│ ├── gitea.md # Self-hosted Git
|
|
│ ├── github.md # GitHub.com via Copilot MCP
|
|
│ ├── context7.md # Library docs
|
|
│ ├── time.md # Current date/time
|
|
│ ├── rommie.md # Desktop automation
|
|
│ ├── hecate.md # Home automation
|
|
│ └── neo4j.md # Graph usage discipline
|
|
├── docs/ # Human reference + LLM context for graph/messaging
|
|
│ ├── roster-changes.md # Adding/replacing/retiring assistants — practice + checklist
|
|
│ ├── personal/ # Character definitions & team overview
|
|
│ ├── work/ # Character definitions & team overview
|
|
│ ├── engineering/ # Character definitions, team overview, subagents catalog
|
|
│ └── tools/ # Per-tool human reference
|
|
│ ├── argos.md # What each tool is, good/bad uses, gotchas
|
|
│ ├── kernos.md
|
|
│ ├── mnemosyne.md
|
|
│ ├── grafana.md
|
|
│ ├── gitea.md
|
|
│ ├── github.md
|
|
│ ├── context7.md
|
|
│ ├── time.md
|
|
│ ├── rommie.md
|
|
│ ├── hecate.md
|
|
│ └── neo4j/ # Neo4j has extensive content; its own subdir
|
|
│ ├── unified-schema.md # Canonical graph schema
|
|
│ ├── shared.md # MCP registry, Agathos sandbox, messaging protocol, assistant directory (LLM-facing)
|
|
│ ├── engineering.md # Engineering team graph context (LLM-facing)
|
|
│ ├── personal.md # Personal team graph context (LLM-facing)
|
|
│ ├── work.md # Work team graph context (LLM-facing)
|
|
│ ├── utils.md # Helper patterns
|
|
│ └── breaking-changes.md
|
|
└── utils/ # Scripts
|
|
├── neo4j-reset.py
|
|
├── neo4j-schema-init.py
|
|
└── neo4j-validate.py
|
|
```
|
|
|
|
## Knowledge Graph
|
|
|
|
All assistants share a single Neo4j knowledge graph. Each assistant owns specific node types and can read broadly across the entire graph. The full schema is in `docs/tools/neo4j/unified-schema.md`.
|
|
|
|
Assistants communicate asynchronously via `Note` nodes with inbox/read tagging — see `docs/tools/neo4j/shared.md` for the messaging protocol.
|
|
|
|
## License
|
|
|
|
MIT
|