Skip to content

Operator handoff for external agents

Audience: Operator (human). This document is for people preparing context for an agent in another repository.

Use this document when you run an AI agent in a different repository that must integrate with the EDOS ecosystem.

Goal

Give a new agent enough context to build a standalone app that follows EDOS architecture and contracts without copying this whole workspace.

Required source docs

Provide these files (or links) to the external agent in this order:

  1. README.md
  2. SCOPE.md
  3. REPOS.md
  4. HOSTNAMES.md (if choosing a production hostname or ed* slug)
  5. ARCHITECTURE.md
  6. IPC.md
  7. HOSTED_APP_CONTRACT.md (when the task is an embeddable hosted web UI: URL bootstrap, manifests, iframe modes — skip for native-only or non-web work)
  8. APP_DISCOVERY_REGISTRY.md (when the task is a composition host, registry index, or app catalog — skip otherwise)
  9. AGENTS.md
  10. Relevant capsules under apps/
  11. DEPLOYMENT.md (if deployment work is in scope)

Copy/paste bootstrap prompt

You are implementing a new standalone app in this repository, but it must integrate with the EDOS ecosystem.

Primary docs base URL:
https://docs.edos.howfe.org/raw

Before coding, read these docs in order (prefer hosted URLs; if unavailable, use local files with same names):
1) https://docs.edos.howfe.org/raw/AGENT_INDEX.md
2) https://docs.edos.howfe.org/raw/README.md
3) https://docs.edos.howfe.org/raw/SCOPE.md
4) https://docs.edos.howfe.org/raw/REPOS.md
5) https://docs.edos.howfe.org/raw/HOSTNAMES.md (if choosing a production hostname)
6) https://docs.edos.howfe.org/raw/ARCHITECTURE.md
7) https://docs.edos.howfe.org/raw/IPC.md (if messaging is involved)
8) https://docs.edos.howfe.org/raw/HOSTED_APP_CONTRACT.md (if embedding hosted web UIs, URL bootstrap, or manifests is involved)
9) https://docs.edos.howfe.org/raw/APP_DISCOVERY_REGISTRY.md (if building a composition host, registry index, or app catalog)
10) https://docs.edos.howfe.org/raw/AGENTS.md
11) relevant https://docs.edos.howfe.org/raw/apps/*.md
12) https://docs.edos.howfe.org/raw/DEPLOYMENT.md (if deployment is part of the task)
13) https://docs.edos.howfe.org/raw/AGENT_DEPLOYMENT_QUICKREF.md (if deployment is part of the task)

Hard constraints:
- This app is standalone; do not assume monorepo tooling.
- If journal/status semantics are used, align with @howfe/elite-dangerous-event-types.
- If cross-window messaging is used, align with @howfe/inter-frame-messenger and documented message types.
- If community third-party APIs are used (SPANSH/EDSM/etc.), route through the cache-server pattern; do not call upstream directly from clients unless explicitly approved.
- EDOS does not import curated game data from other Elite Dangerous applications; use citable public references or verify and maintain the data in-repo (DOC_CONVENTIONS.md).
- If the task is **Windows desktop installers** or a **native shell** that embeds hosted EDOS web UIs: **do not** introduce a second Tauri app in this repo — URL-wired EXEs and the build API live in **elite-dangerous-local-journal-reader** (`build-service/`). Read https://docs.edos.howfe.org/raw/apps/elite-dangerous-local-journal-reader.md (and https://docs.edos.howfe.org/raw/apps/elite-dangerous-journal-event-viewer.md for EDJEV) before designing packaging.
- Keep assumptions explicit; mark uncertainty as TODO: Verify with a concrete verification step.

Deliverables:
- Brief architecture note for this repository
- Implementation
- Integration notes (how this app connects to the EDOS ecosystem)
- `docker-compose.yaml` at repo root that matches EDOS production (see [DEPLOYMENT.md](./DEPLOYMENT.md#compose-file-for-production-agents-new-apps)), if deployment is expected
- Docs updates in this repository

Handoff checklist (human operator)

Before launching the external agent, provide:

  1. The exact task goal (what app should do).
  2. Which EDOS contracts apply (journal, IPC, third-party APIs).
  3. Which deployment target applies (local only, hosted, containerized).
  4. Any known forbidden choices (e.g. direct upstream API calls).
  5. Where the agent should write its own docs in the target repo.

Minimum acceptance criteria for the external app

  • No monorepo coupling assumptions.
  • Uses shared contracts/libraries where applicable.
  • Community API traffic goes through cache/proxy pattern.
  • Includes a short integration section in target repo docs.
  • Includes basic run/build/deploy notes.

Optional: lightweight validation prompt

Use this after implementation to audit compliance:

Review this repository for compliance with EDOS integration rules:
- standalone repo boundaries
- journal/status typing contract
- postMessage contract (if used)
- fair-use cache requirement for community third-party APIs
- no importing curated game data from other Elite Dangerous applications
List any violations with file paths and concrete fixes.