5.5 KiB
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:
EventArtifactSessionId,EventId,CorrelationId,CausationIdStageId,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)
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