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. ARCHITECTURE.md
  5. IPC.md
  6. AGENTS.md
  7. Relevant capsules under apps/
  8. 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/ARCHITECTURE.md
6) https://docs.edos.howfe.org/raw/IPC.md (if messaging is involved)
7) https://docs.edos.howfe.org/raw/AGENTS.md
8) relevant https://docs.edos.howfe.org/raw/apps/*.md
9) https://docs.edos.howfe.org/raw/DEPLOYMENT.md (if deployment is part of the task)
10) 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.
- 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
List any violations with file paths and concrete fixes.