diff --git a/AGENTS.md b/AGENTS.md index 972d8a80..9064c2bd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,7 +32,7 @@ OpenWork is an open-source alternative to Claude Cowork. ## Repository Guidance - Write new PRDs under `packages/app/pr/.md` (see `.opencode/skills/prd-conventions/SKILL.md`). -- Use `VISION.md`, `PRINCIPLES.md`, `PRODUCT.md`, and `ARCHITECTURE.md` to understand the "why" and requirements so you can guide your decisions. +- Use `VISION.md`, `PRINCIPLES.md`, `PRODUCT.md`, `ARCHITECTURE.md`, and `INFRASTRUCTURE.md` to understand the "why" and requirements so you can guide your decisions. ## Local Structure diff --git a/INFRASTRUCTURE.md b/INFRASTRUCTURE.md new file mode 100644 index 00000000..082cea3c --- /dev/null +++ b/INFRASTRUCTURE.md @@ -0,0 +1,64 @@ +# OpenWork Infrastructure Principles + +OpenWork is an experience layer. OpenCode is the engine. This document defines how infrastructure is built so every component is usable on its own, composable as a sidecar, and easy to automate. + +## Core Principles + +1) CLI-first, always +- Every infrastructure component must be runnable via a single CLI command. +- The OpenWork UI may wrap these, but never replace or lock them out. + +2) Unix-like interfaces +- Prefer simple, composable boundaries: JSON over stdout, flags, and env vars. +- Favor readable logs and predictable exit codes. + +3) Sidecar-composable +- Any component must run as a sidecar without special casing. +- The UI should connect to the same surface area the CLI exposes. + +4) Clear boundaries +- OpenCode remains the engine; OpenWork adds a thin config + UX layer. +- When OpenCode exposes a stable API, use it instead of re-implementing. + +5) Local-first, graceful degradation +- Default to local execution. +- If a sidecar is missing or offline, the UI falls back to read-only or explicit user guidance. + +6) Portable configuration +- Use config files + env vars; avoid hidden state. +- Keep credentials outside git and outside the repo. + +7) Observability by default +- Provide health endpoints and structured logs. +- Record audit events for every config mutation. + +8) Security + scoping +- All filesystem access is scoped to explicit workspace roots. +- Writes require explicit host approval when requested remotely. + +## Applied to Current Components + +### OpenCode Engine +- Always usable via `opencode` CLI. +- OpenWork never replaces the CLI; it only connects to the engine. + +### OpenWork Server +- Runs standalone via `openwork-server` CLI. +- Provides filesystem-backed config surfaces (skills, plugins, MCP, commands). +- Sidecar lifecycle is described in `packages/app/pr/openwork-server.md`. + +### Owpenbot +- Runs standalone via `owpenwork` CLI. +- Must be able to use OpenWork server for config and approvals. + +## Non-goals + +- Replacing OpenCode primitives with custom abstractions. +- Building multi-tenant or cloud-managed infrastructure. + +## References + +- `VISION.md` +- `PRINCIPLES.md` +- `ARCHITECTURE.md` +- `packages/app/pr/openwork-server.md`