docs(dox): build out the DOX AGENTS.md hierarchy
Root Child DOX Index assembled, plus a per-module AGENTS.md across the tree (core/*, infrastructure/*, apps/*, testing/*, and docs/examples/frontend/etc), each following the DOX section shape: Purpose, Ownership, Local Contracts, Work Guidance, Verification, Child DOX Index.
This commit is contained in:
@@ -0,0 +1,31 @@
|
||||
# apps/
|
||||
|
||||
## Purpose
|
||||
|
||||
Entry-point applications that compose core modules into runnable processes. Each app wires infrastructure and core together; no business logic lives here.
|
||||
|
||||
## Ownership
|
||||
|
||||
All apps in this subtree. Dependency rule: `apps → core → infrastructure`. Apps may not import sibling app modules.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- Apps depend on `core:*` and `infrastructure:*` only — never on each other.
|
||||
- Configuration loading, process lifecycle, and entrypoint wiring live here.
|
||||
- No domain logic in apps; delegate to core services.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
Follow the Kotlin rules and anti-patterns in the root CLAUDE.md for all JVM apps. `apps/tui-go` is a separate Go module — see its own AGENTS.md.
|
||||
|
||||
## Verification
|
||||
|
||||
Each app has its own verification command. See child AGENTS.md.
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
- `apps/cli` — Clikt CLI; sends commands to `apps/server` over HTTP + WebSocket
|
||||
- `apps/desktop` — stub module, not yet implemented
|
||||
- `apps/server` — Ktor HTTP API + WebSocket server; orchestrates core kernel
|
||||
- `apps/tui-go` — Go/Bubble Tea terminal UI; WebSocket client of `apps/server`
|
||||
- `apps/worker` — stub module, not yet implemented
|
||||
@@ -0,0 +1,30 @@
|
||||
# apps/cli
|
||||
|
||||
## Purpose
|
||||
|
||||
Clikt-based command-line interface. Translates user commands into HTTP requests and WebSocket connections against `apps/server`.
|
||||
|
||||
## Ownership
|
||||
|
||||
All sources under `apps/cli/src/`.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- Commands: `session`, `run`, `task`, `provider`, `approve`, `undo`, `events`, `status`, `replay`, `stats`, `health`
|
||||
- Communicates with server via HTTP REST and WebSocket (`CliWsClient`)
|
||||
- No business logic; all orchestration is delegated to the server
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- Follow Kotlin rules in root CLAUDE.md (runCatching, suspend, no blocking I/O on main thread)
|
||||
- New commands go under `commands/`, follow the existing Clikt subcommand pattern
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :apps:cli:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child AGENTS.md (leaf module).
|
||||
@@ -0,0 +1,27 @@
|
||||
# apps/desktop
|
||||
|
||||
## Purpose
|
||||
|
||||
Stub module reserved for a future desktop GUI application. Not yet implemented.
|
||||
|
||||
## Ownership
|
||||
|
||||
`apps/desktop/` — currently only a placeholder `Main.kt`.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
None defined yet.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
Do not add functionality here until the desktop epic is planned. Follow Kotlin rules in root CLAUDE.md when work begins.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :apps:desktop:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child AGENTS.md (leaf module).
|
||||
@@ -0,0 +1,45 @@
|
||||
# apps/server
|
||||
|
||||
## Purpose
|
||||
|
||||
Ktor HTTP + WebSocket server. Exposes the orchestration kernel to CLI and TUI clients, manages session lifecycle, and streams events over WebSocket.
|
||||
|
||||
## Ownership
|
||||
|
||||
All sources under `apps/server/src/`.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
### HTTP REST routes
|
||||
- `GET/POST /sessions` — session browse and start
|
||||
- `POST /sessions/{id}/resume` — resume a session after restart
|
||||
- `GET/POST /tasks` — task listing and management
|
||||
- `GET/POST /providers` — provider configuration
|
||||
- `GET/POST /workflows` — workflow management
|
||||
- `GET /health` — health report (probes: event-store, llama-server, disk watermark)
|
||||
- `GET /stats` — metrics report (MetricsProjection)
|
||||
|
||||
### WebSocket protocol (`/ws`)
|
||||
- **ServerMessage** (server → client): sealed hierarchy — `SessionMessage` (event-derived, carries `sequence` + `sessionSequence`) and `NonEventMessage` (control/infra). Variants include session lifecycle, approval requests, clarification requests, narration, proposed workflows, health/metrics pushes.
|
||||
- **ClientMessage** (client → server): `StartSession`, `ApproveToolCall`, `RejectToolCall`, `GrantApproval`, `AnswerClarification`, `SetChatMode`, and others.
|
||||
- All protocol types are in `protocol/` (Dtos.kt, ServerMessage.kt, ClientMessage.kt, ProtocolSerializer.kt).
|
||||
|
||||
### Health monitoring
|
||||
- `HealthMonitor` runs probes on a schedule; results folded via `HealthProjection` into `HealthState`.
|
||||
- Adding a probe: implement `HealthProbe`, register in `ServerModule`.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- Follow Kotlin rules in root CLAUDE.md.
|
||||
- Route handlers must not contain domain logic — delegate to core services injected via `ServerModule`.
|
||||
- New WS message variants require updating both `ServerMessage`/`ClientMessage` sealed classes and `ProtocolSerializer`.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :apps:server:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child AGENTS.md (leaf module).
|
||||
@@ -0,0 +1,37 @@
|
||||
# apps/tui-go
|
||||
|
||||
## Purpose
|
||||
|
||||
Terminal UI for correx. A Go/Bubble Tea application that connects to `apps/server` over WebSocket and renders session state in a "Soft + blue" visual style.
|
||||
|
||||
## Ownership
|
||||
|
||||
All sources under `apps/tui-go/`. Separate Go module (`github.com/correx/tui-go`) — independent build and test toolchain from the Gradle/Kotlin apps.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
- Connects to `apps/server` at the configured WebSocket endpoint; does not import any Kotlin/JVM code.
|
||||
- **Receives** `ServerMessage` JSON over WebSocket (session lifecycle, approval requests, clarification requests, narration, proposed workflows, health/metrics).
|
||||
- **Sends** `ClientMessage` JSON (StartSession, ApproveToolCall, RejectToolCall, AnswerClarification, SetChatMode, etc.).
|
||||
- Protocol types are mirrored in `internal/protocol/` — must stay in sync with `apps/server/src/.../protocol/`.
|
||||
- Visual theme: "Soft + blue" (see `internal/app/theme.go`). Reference design lives in `docs/visual/ref/`.
|
||||
- Key layout defined in `internal/app/key.go`.
|
||||
- Main model in `internal/app/model.go`; update loop in `internal/app/update.go`; rendering in `internal/app/view.go`.
|
||||
- Overlays (sessions, tasks, config, ideas) in `internal/app/overlays.go` and sibling files.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
- Standard Go conventions: `gofmt`-formatted, exported names for cross-package types, unexported for internal.
|
||||
- Add new WS message handling in `internal/ws/client.go` → dispatch via Bubble Tea `Msg` types → handled in `update.go`.
|
||||
- New UI panels follow the existing card/overlay pattern (see `clarcard.go`, `proposecard.go`).
|
||||
- Keep theme constants in `theme.go`; do not hardcode colors elsewhere.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
cd apps/tui-go && go build ./... && go test ./...
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child AGENTS.md (leaf module).
|
||||
@@ -0,0 +1,27 @@
|
||||
# apps/worker
|
||||
|
||||
## Purpose
|
||||
|
||||
Stub module reserved for a future background worker process. Not yet implemented.
|
||||
|
||||
## Ownership
|
||||
|
||||
`apps/worker/` — currently only a placeholder `Main.kt`.
|
||||
|
||||
## Local Contracts
|
||||
|
||||
None defined yet.
|
||||
|
||||
## Work Guidance
|
||||
|
||||
Do not add functionality here until the worker epic is planned. Follow Kotlin rules in root CLAUDE.md when work begins.
|
||||
|
||||
## Verification
|
||||
|
||||
```
|
||||
./gradlew :apps:worker:test --rerun-tasks
|
||||
```
|
||||
|
||||
## Child DOX Index
|
||||
|
||||
No child AGENTS.md (leaf module).
|
||||
Reference in New Issue
Block a user