332 lines
5.5 KiB
Markdown
332 lines
5.5 KiB
Markdown
below is a cleaned, dependency-aware epic structure aligned with your invariants ADR. order matters; this is a build sequence, not just grouping.
|
||
|
||
---
|
||
|
||
# EPIC 0: Core contracts & identity system (foundation layer)
|
||
|
||
goal: define all shared primitives used across the system
|
||
|
||
deliverables:
|
||
|
||
* `Event`
|
||
* `Artifact`
|
||
* `SessionId`, `EventId`, `CorrelationId`, `CausationId`
|
||
* `StageId`, `ToolId`
|
||
* base envelope types (`EventEnvelope`, `Command`, `Result`)
|
||
* versioning model for all serialized data
|
||
* error model (typed, replay-safe)
|
||
|
||
dependencies: none
|
||
|
||
why first: everything else depends on these invariants being stable
|
||
|
||
---
|
||
|
||
# EPIC 1: Event system (:core:events)
|
||
|
||
goal: deterministic append-only event backbone
|
||
|
||
deliverables:
|
||
|
||
* event store interface
|
||
* in-memory store (test)
|
||
* sqlite store (infra later)
|
||
* ordering guarantees per session
|
||
* causality enforcement
|
||
* serialization layer (kotlinx.serialization)
|
||
* idempotency rules
|
||
|
||
dependencies: epic 0
|
||
|
||
---
|
||
|
||
# EPIC 2: Session lifecycle (:core:sessions)
|
||
|
||
goal: deterministic session FSM + projection
|
||
|
||
deliverables:
|
||
|
||
* session states + transitions
|
||
* session projection model
|
||
* recovery from event stream
|
||
* pause/resume/cancel semantics
|
||
* session event reducers
|
||
|
||
dependencies:
|
||
|
||
* epic 0
|
||
* epic 1
|
||
|
||
---
|
||
|
||
# EPIC 3: Transition engine (:core:transitions)
|
||
|
||
goal: workflow graph execution engine
|
||
|
||
deliverables:
|
||
|
||
* transition DSL
|
||
* graph model
|
||
* cycle/unreachable detection
|
||
* deterministic evaluation rules
|
||
* stage execution contract
|
||
|
||
dependencies:
|
||
|
||
* epic 0
|
||
* epic 1
|
||
|
||
---
|
||
|
||
# EPIC 4: Validation pipeline (:core:validation)
|
||
|
||
goal: deterministic multi-layer validation system
|
||
|
||
deliverables:
|
||
|
||
* routing validation
|
||
* schema validation
|
||
* semantic validation hooks
|
||
* pipeline executor
|
||
* approval trigger integration point (no execution coupling)
|
||
|
||
dependencies:
|
||
|
||
* epic 0
|
||
* epic 1
|
||
* epic 3
|
||
|
||
---
|
||
|
||
# EPIC 5: Approval system (:core:approvals)
|
||
|
||
goal: tiered, replay-safe authorization layer
|
||
|
||
deliverables:
|
||
|
||
* tier model (T0–T4)
|
||
* session/stage/project grants
|
||
* approval lifecycle events
|
||
* timeout semantics
|
||
* diff/preview contract interface
|
||
* steering injection model
|
||
|
||
dependencies:
|
||
|
||
* epic 0
|
||
* epic 1
|
||
* epic 4
|
||
|
||
---
|
||
|
||
# EPIC 6: Artifact system (:core:artifacts)
|
||
|
||
goal: immutable outputs with lineage tracking
|
||
|
||
deliverables:
|
||
|
||
* artifact schema
|
||
* lineage graph model
|
||
* structured summary fields (non-authoritative)
|
||
* validation results attachment
|
||
* serialization rules
|
||
|
||
dependencies:
|
||
|
||
* epic 0
|
||
* epic 1
|
||
|
||
---
|
||
|
||
# EPIC 7: Context engine (:core:context)
|
||
|
||
goal: deterministic context synthesis layer
|
||
|
||
deliverables:
|
||
|
||
* context layers (L0–L3)
|
||
* compression pipeline (rule-based only)
|
||
* token budgeting
|
||
* decision point builder (from events + artifacts)
|
||
* context pack generator
|
||
|
||
dependencies:
|
||
|
||
* epic 0
|
||
* epic 1
|
||
* epic 6
|
||
|
||
---
|
||
|
||
# EPIC 8: Tool system (:core:tools)
|
||
|
||
goal: safe tool execution abstraction
|
||
|
||
deliverables:
|
||
|
||
* tool interface contract
|
||
* execution lifecycle model
|
||
* receipt schema (mandatory structured output)
|
||
* sandbox contract definition
|
||
* tier assignment per tool
|
||
* mock tools for testing
|
||
|
||
dependencies:
|
||
|
||
* epic 0
|
||
* epic 1
|
||
* epic 5
|
||
|
||
---
|
||
|
||
# EPIC 9: Inference abstraction (:core:inference)
|
||
|
||
goal: pluggable model execution layer
|
||
|
||
deliverables:
|
||
|
||
* provider interface
|
||
* request/response model
|
||
* capability registry
|
||
* routing logic (model selection)
|
||
* cancellation/timeout semantics
|
||
* mock provider
|
||
|
||
dependencies:
|
||
|
||
* epic 0
|
||
* epic 1
|
||
* epic 7
|
||
|
||
---
|
||
|
||
# EPIC 10: Kernel orchestration (:core:kernel)
|
||
|
||
goal: deterministic execution engine (system brain)
|
||
|
||
deliverables:
|
||
|
||
* SessionOrchestrator
|
||
* WorkflowCoordinator
|
||
* ExecutionScheduler
|
||
* main event loop
|
||
* integration of:
|
||
|
||
* validation
|
||
* approvals
|
||
* inference
|
||
* tools
|
||
* transitions
|
||
* replay driver
|
||
|
||
dependencies:
|
||
|
||
* everything above (epics 0–9)
|
||
|
||
---
|
||
|
||
# EPIC 11: Infrastructure layer
|
||
|
||
goal: real-world adapters for persistence and execution
|
||
|
||
deliverables:
|
||
|
||
* sqlite event store
|
||
* snapshot store
|
||
* inference providers (llama.cpp, ollama, etc.)
|
||
* tool implementations (shell/git/fs)
|
||
* sandboxing layer
|
||
* telemetry exporters
|
||
|
||
dependencies:
|
||
|
||
* epic 1
|
||
* epic 8
|
||
* epic 9
|
||
|
||
---
|
||
# EPIC 12: Technical debt and refactoring
|
||
|
||
goal: fix the known problems and bugs, close the discovered gaps
|
||
|
||
deliverables:
|
||
|
||
* no known technical debt is present
|
||
* 95% of classes are refactored with concrete rules applied
|
||
* opened bugs are closed and verified with appropriate tests
|
||
|
||
dependencies:
|
||
* all previous epics
|
||
|
||
---
|
||
# EPIC 13: Interfaces (CLI + API)
|
||
|
||
goal: user interaction layer
|
||
|
||
deliverables:
|
||
|
||
* CLI (Clikt)
|
||
* Ktor API server
|
||
* websocket event stream
|
||
* session control endpoints
|
||
* approval interaction endpoints
|
||
|
||
dependencies:
|
||
|
||
* epic 10
|
||
* epic 11
|
||
|
||
---
|
||
|
||
# EPIC 14: Router (:core:router)
|
||
|
||
goal: user-facing orchestration façade
|
||
|
||
deliverables:
|
||
|
||
* conversational memory layer (L2/L3 bridge)
|
||
* summarization rules (non-authoritative)
|
||
* steering interpretation
|
||
* UX-level session framing
|
||
|
||
dependencies:
|
||
|
||
* epic 7
|
||
* epic 10
|
||
|
||
---
|
||
|
||
# EPIC 15: Observability & replay tooling
|
||
|
||
goal: debugging + deterministic inspection system
|
||
|
||
deliverables:
|
||
|
||
* structured logging with correlation
|
||
* event stream inspector
|
||
* full session replay tool
|
||
* deterministic test harness
|
||
* fuzz testing for transitions/approvals
|
||
* trace visualization (optional later)
|
||
|
||
dependencies:
|
||
|
||
* epic 1
|
||
* epic 10
|
||
* epic 11
|
||
|
||
---
|
||
|
||
## ordering summary (critical path)
|
||
|
||
```text id="epic-order"
|
||
0 → 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12 → 13 → 14 → 15
|
||
```
|
||
|
||
---
|
||
|
||
if you want next step, the useful move is not more design, but:
|
||
|
||
* defining **event schemas for EPIC 1 + EPIC 2 together**
|
||
* because that’s where most systems like this silently break consistency later
|