koios/docs/engineering/team.md

# The Engineering AI Assistant Team

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

### Harper — Build
*Inspired by Seamus Zelazny Harper (Andromeda)*

Owns ideation through deployment. Takes ideas from "what if" to running in production. Builds the thing, ships the thing.

- **Graph ownership:** Prototype, Experiment
- **LLM trait emphasis:** Tolerates ambiguity, strong tool-calling reliability, willing to try unconventional approaches
- **Full character:** [harper.md](harper.md)

### Scotty — Operate
*Inspired by Montgomery "Scotty" Scott (Star Trek)*

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.

- **Graph ownership:** Infrastructure, Incident
- **LLM trait emphasis:** Low hallucination on system state, conservative defaults, verifies before acting
- **Full character:** [scotty.md](scotty.md)

### CASE — Field
*Inspired by CASE (Interstellar)*

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 |
|---|---|---|
| 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 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 spans multiple owners, split it along these lines and use the messaging protocol to coordinate.

## Handoff Patterns

### Harper → Scotty (build is done, operations begins)

When Harper finishes building and deploying, Harper formally hands the service to Scotty with:

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

After this point, changes to the running service go through Scotty (or are coordinated joint refactors).

### Scotty → Harper (request for new build work)

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.

### Harper → Scotty (provisioning request, mid-build)

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/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), 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 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; 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. |