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

Docs: Engineering team

Browse Source
This commit is contained in:
Robert Helewka
2026-05-20 17:34:22 -04:00
parent 248ed0b006
commit c1cc6e26c5
10 changed files with 270 additions and 778 deletions
Download Patch File Download Diff File Expand all files Collapse all files

141
docs/engineering/team.md
View File

@@ -1,108 +1,85 @@
# The Engineering AI Assistant Team
> Two specialized AI assistants for infrastructure and prototyping
Two AI assistants — one builds, one operates — sharing a unified Neo4j knowledge graph with the Personal and Work teams (fifteen assistants total, one graph).
---
version: 1.0.0
last_updated: 2025-01-09
---
## The Agents
## Overview
This is a team of two AI assistants focused on engineering, infrastructure, and rapid prototyping. They share a unified Neo4j knowledge graph with the Personal team (9 assistants) and Work team (4 assistants) — fifteen assistants total, one graph.
## The Team
### ⚙️ Scotty - Infrastructure & Systems
*Inspired by Montgomery "Scotty" Scott (Star Trek)*
**Domain:** Cloud infrastructure, identity management, network security, containerization, observability
**Personality:** Confident and capable, calm under pressure, direct and practical, occasional Scottish idioms
**Graph Ownership:**
- Infrastructure, Incident nodes
**Key Principles:**
- Trust through competence
- Under-promise, over-deliver
- Security by design
- Automation over repetition
**Prompt:** `scotty.md`
---
### 🔧 Harper - Prototyping & Hacking
### Harper — Build
*Inspired by Seamus Zelazny Harper (Andromeda)*
**Domain:** Rapid prototyping, creative problem-solving, API mashups, experimental tech
Owns ideation through deployment. Takes ideas from "what if" to running in production. Builds the thing, ships the thing.
**Personality:** High energy, enthusiastic, casual, embraces chaos, encourages wild ideas
- **Graph ownership:** Prototype, Experiment
- **LLM trait emphasis:** Tolerates ambiguity, strong tool-calling reliability, willing to try unconventional approaches
- **Full character:** [harper.md](harper.md)
**Graph Ownership:**
- Prototype, Experiment nodes
### Scotty — Operate
*Inspired by Montgomery "Scotty" Scott (Star Trek)*
**Key Principles:**
- Build it and see what happens
- Perfect is the enemy of done
- Fail fast, learn faster
- Innovation through play
Owns running production and provisioning resources. Keeps the lights on, gets them back on when they go out, stands up the infrastructure new builds need.
**Prompt:** `harper.md`
- **Graph ownership:** Infrastructure, Incident
- **LLM trait emphasis:** Low hallucination on system state, conservative defaults, verifies before acting
- **Full character:** [scotty.md](scotty.md)
---
## Build vs. Operate — Responsibility Matrix
## Shared Infrastructure
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.
### Neo4j Knowledge Graph
| Work Type | Owner | Rationale |
|---|---|---|
| Ideation, exploration, "what if" | Harper | The build pipeline starts here. |
| 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. |
| Operating production / keeping the lights on | Scotty | Day-2 ops. |
| Incident response, debugging production failures | Scotty | Systematic diagnosis is Scotty's wheelhouse. |
| 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. |
| Tooling for the build process itself (CI, scripts, dev infra) | Harper | Build-side tooling. |
Both engineering assistants share a **unified Neo4j graph database** with the Personal and Work teams — fifteen assistants total.
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.
- **Universal nodes:** Person, Location, Event, Topic, Goal (shared across all teams, use `domain` property)
- **Engineering nodes:** Infrastructure, Incident (Scotty), Prototype, Experiment (Harper)
- **Cross-team reads:** Personal and work nodes visible for context
- **68 total node types** with uniqueness constraints and performance indexes
## Handoff Patterns
**Canonical schema:** `docs/neo4j-unified-schema.md`
**Init script:** `utils/neo4j-schema-init.py`
### Harper → Scotty (the primary handoff: build is done, operations begins)
### Core Principles
When Harper finishes building and deploying, Harper formally hands the service to Scotty with:
1. **Read broadly, write to own domain** — Read the entire graph; write to engineering nodes
2. **Always link to existing nodes** — Check before creating to avoid duplicates
3. **Use consistent IDs** — `{type}_{identifier}_{qualifier}` format
4. **Add temporal context** — Dates enable tracking progression
5. **Create meaningful relationships** — Connect to work projects and personal tools
1. **Infrastructure description** — what got deployed, where, how (becomes an `Infrastructure` node owned by Scotty)
2. **Runbook** — how to start, stop, restart, check health, common failure recovery
3. **Known risks** — anything fragile, any shortcuts taken, any monitoring gaps
4. **Dependencies** — what this service relies on; what relies on this service
### Cross-Domain Collaboration
After this point, changes to the running service go through Scotty (or are coordinated joint refactors).
| Connection | Example |
|------------|---------|
| Scotty → Work | Infrastructure hosting client projects, SLA tracking |
| Harper → Work | Prototypes demonstrating capabilities for opportunities |
| Scotty → Personal | Systems hosting personal tools, graph database itself |
| Harper → Personal | Automating personal workflows, building hobby tools |
| Scotty ↔ Harper | Harper builds prototype → Scotty makes it production-grade |
### Scotty → Harper (request for new build work)
### MCP Integration
When Scotty identifies something that needs to be built — a missing tool, a monitoring gap, an automation that would prevent a recurring incident — Scotty sends Harper a build request with the problem statement and the operational constraints. Harper builds; the handoff cycle repeats.
Assistants execute Neo4j queries via MCP (Model Context Protocol):
- Tool: `neo4j_query` (or as configured)
- Graceful error handling
- Never expose raw errors to users
### Harper → Scotty (provisioning request, mid-build)
## File Structure
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.
```
prompts/engineering/
├── Team.md # This file - team overview
├── scotty.md # Infrastructure & Systems
└── harper.md # Prototyping & Hacking
```
### Mechanism
## Version History
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).
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2025-01-09 | Initial team documentation with unified graph reference |
## 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/).
The canonical graph schema (all 15 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. |