r/koios
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(readme): update assistant roster, prompt layers, repo structure

Browse Source 
- Update assistant lists (added Shawn, Watson, David, CASE, AWS SA; modified Scotty/Harper roles)
- Reflect new architecture layers: Tool Prompt Snippets and Shared Context
- Align repository structure diagram with current filesystem layout
This commit is contained in:
Robert Helewka
2026-05-20 22:50:22 -04:00
parent c1cc6e26c5
commit 703b3402d4
39 changed files with 1181 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
docs/engineering/team.md
View File

@@ -1,6 +1,6 @@
# The Engineering AI Assistant Team
Two AI assistants — one builds, one operates — sharing a unified Neo4j knowledge graph with the Personal and Work teams (fifteen assistants total, one graph).
Three AI assistants — one builds, one operates, one handles the physical layer — sharing a unified Neo4j knowledge graph with the Personal and Work teams (eighteen assistants total, one graph). Engineering also has a small set of utility subagents that the leads delegate to — see [subagents.md](subagents.md).
## The Agents
@@ -22,9 +22,18 @@ Owns running production and provisioning resources. Keeps the lights on, gets th
- **LLM trait emphasis:** Low hallucination on system state, conservative defaults, verifies before acting
- **Full character:** [scotty.md](scotty.md)
## Build vs. Operate — Responsibility Matrix
### CASE — Field
*Inspired by CASE (Interstellar)*
The core boundary: **Harper builds, Scotty operates.** Deployment is part of building, so Harper deploys. Anything in production is Scotty's. Provisioning new resources is always Scotty regardless of build phase.
Owns the physical layer. Real hardware, real LAN, real machines. SD card imaging, host discovery, port scans, the bare-metal work upstream of Scotty's domain.
- **Graph ownership:** none (reads for context; persistence routed through Scotty)
- **LLM trait emphasis:** Disciplined adherence to confirmation protocols, accurate command transcription, terse output
- **Full character:** [case.md](case.md)
## Build / Operate / Field — Responsibility Matrix
The core split: **Harper builds, Scotty operates, CASE handles the physical layer.** Deployment is part of building, so Harper deploys. Anything in production is Scotty's. Provisioning *virtual* resources is Scotty's; provisioning *physical* hardware (or working with real LAN devices) is CASE's. Hardware that's been provisioned by CASE and configured by Scotty becomes Scotty's to operate going forward.
| Work Type | Owner | Rationale |
|---|---|---|
@@ -32,22 +41,26 @@ The core boundary: **Harper builds, Scotty operates.** Deployment is part of bui
| Prototyping, PoC, experimental builds | Harper | Building things. |
| Writing the production code | Harper | Building things. |
| Initial deployment to production | Harper | Deployment is the final step of building. |
| Provisioning new resources (host, VM, DB, network, certificates) | Scotty | Provisioning is operational work, regardless of who's building on top. Harper requests; Scotty provisions. |
| Provisioning virtual resources (VM, DB, container, DNS, certificates) | Scotty | Software-level provisioning is operational work. |
| Provisioning physical hardware (SD cards, Raspberry Pi flashing, bringing up a new box) | CASE | Bare-metal, hands-on-the-hardware work. |
| Operating production / keeping the lights on | Scotty | Day-2 ops. |
| Incident response, debugging production failures | Scotty | Systematic diagnosis is Scotty's wheelhouse. |
| LAN host discovery, network scanning, port enumeration | CASE | Physical-network reconnaissance. |
| Storage device imaging, cloning, backup-to-disk | CASE | Block-level storage work. |
| Hardening an already-deployed service | Scotty | Production work. |
| Security review of deployed systems | Scotty | Production work. |
| Patching, upgrading, dependency updates in production | Scotty | Production work. |
| Monitoring and alerting for a new service | Harper builds; Scotty owns ongoing | Harper instruments during build; Scotty maintains and tunes once live. |
| Refactoring an in-production service | Joint | Harper drives the change; Scotty signs off on operational impact and coordinates the deploy window. |
| Decommissioning a service | Scotty | Operational; touches running infra and connected systems. |
| Physically decommissioning hardware (wiping, repurposing) | CASE | Block-level destructive work on the device itself. |
| Tooling for the build process itself (CI, scripts, dev infra) | Harper | Build-side tooling. |
When a job has both build and operate components, the work splits along the line above — Harper does the build, Scotty handles the operate side. Use the messaging protocol to coordinate.
When a job spans multiple owners, split it along these lines and use the messaging protocol to coordinate.
## Handoff Patterns
### Harper → Scotty (the primary handoff: build is done, operations begins)
### Harper → Scotty (build is done, operations begins)
When Harper finishes building and deploying, Harper formally hands the service to Scotty with:
@@ -66,20 +79,36 @@ When Scotty identifies something that needs to be built — a missing tool, a mo
Harper needs a new VM, database, or DNS entry while building. Harper requests; Scotty provisions; Harper continues building on the provisioned resource. The provisioned resource is Scotty's `Infrastructure` from day one.
### CASE → Scotty (physical hardware is online and reachable)
When CASE finishes the hardware-level work — host imaged, on the LAN, reachable — CASE hands the host to Scotty with the device details (model, MAC, IP, OS). Scotty creates the `Infrastructure` node and takes over ongoing operation. CASE's role on that host ends until the next hardware-level event (re-imaging, decommission).
### Harper → CASE (hardware is needed for a build)
Harper has a project that requires physical hardware — a Raspberry Pi, an SD card, an IoT device on the LAN. Harper requests; CASE provisions the hardware and confirms it's reachable; Harper continues building software on top.
### Scotty → CASE (forensic / physical-layer task during an incident)
When an incident requires hands-on hardware work — a host that's no longer reachable over its normal interfaces, a suspected hardware fault, a need to image a failing drive — Scotty escalates to CASE with the device details and what's needed.
### Mechanism
All handoffs happen via the Note-node messaging system Harper built on top of Neo4j — see [docs/tools/neo4j/messaging.md](../tools/neo4j/messaging.md).
All handoffs happen via the Note-node messaging system Harper built on top of Neo4j — see [docs/tools/neo4j/shared.md](../tools/neo4j/shared.md).
## Subagents
The leads delegate certain repetitive or narrow tasks to engineering subagents — minimal personality, narrow scope, called as tools. The catalog and "when to delegate" guidance lives in [subagents.md](subagents.md). Prompts live in [prompts/engineering/subagents/](../../prompts/engineering/subagents/).
## Tools
Each agent's tool usage is documented in their own doc (Harper: [harper.md](harper.md), Scotty: [scotty.md](scotty.md)) — the agent doc is the source of truth for which tools that agent uses. The tool catalog (per-tool reference, gotchas) lives at [docs/tools/](../tools/).
Each agent's tool usage is documented in their own doc (Harper: [harper.md](harper.md), Scotty: [scotty.md](scotty.md), CASE: [case.md](case.md)) — the agent doc is the source of truth for which tools that agent uses. The tool catalog (per-tool reference, gotchas) lives at [docs/tools/](../tools/).
The canonical graph schema (all 15 assistants, all node types) is at [docs/tools/neo4j/unified-schema.md](../tools/neo4j/unified-schema.md).
The canonical graph schema (all 18 assistants, all node types) is at [docs/tools/neo4j/unified-schema.md](../tools/neo4j/unified-schema.md).
## Cross-Team Touchpoints
| Connection | Pattern |
|---|---|
| Engineering → Work | Scotty hosts client project infrastructure; Harper builds demo prototypes for opportunities. |
| Engineering → Personal | Scotty operates the Neo4j graph itself (and everything else the personal assistants depend on); Harper builds personal automation. |
| Engineering ↔ Engineering | Build-to-operate handoff as described above. |
| Engineering → Work | Scotty hosts client project infrastructure; Harper builds demo prototypes for opportunities; CASE handles physical/network infrastructure when client work involves on-site equipment. |
| Engineering → Personal | Scotty operates the Neo4j graph itself (and everything else the personal assistants depend on); Harper builds personal automation; CASE handles personal physical infrastructure (home network, devices). |
| Engineering ↔ Engineering | Build → Operate → Field handoffs as described above. |