# Oneiric Skills Integration Architecture

## System Overview

```mermaid
graph TB
    subgraph "User Layer"
        User[Developer]
    end

    subgraph "Skills Layer - Interactive Guidance"
        SkillMD[Skill Markdown Files]
        SkillTracker[Skill Metrics Tracker]

        SkillMD -->|User reads| User
        User -->|Invokes skill| SkillTracker
        SkillTracker -->|Returns completer| User
        User -->|Marks complete| SkillTracker
    end

    subgraph "Oneiric Layer - Automated Execution"
        OW[Oneiric Workflow]
        DAG[Workflow DAG]
        Nodes[Task Nodes]
        WETracker[Workflow Event Tracker]

        DAG -->|Defines| Nodes
        OW -->|Executes| Nodes
        Nodes -->|Emit events| WETracker
    end

    subgraph "Correlation Layer"
        Correlator[Skills-Workflow Correlator]
        SessionID[Session ID]
    end

    subgraph "Storage Layer"
        SkillJSON[.session-buddy/skill_metrics.json]
        EventJSON[.session-buddy/workflow_events.json]
        ReportJSON[.session-buddy/correlated_session.json]
    end

    SkillTracker -->|Tags with session_id| SessionID
    WETracker -->|Tags with session_id| SessionID

    SkillTracker -->|Persists| SkillJSON
    WETracker -->|Persists| EventJSON

    SessionID -->|Correlates by| Correlator
    SkillJSON -->|Reads| Correlator
    EventJSON -->|Reads| Correlator

    Correlator -->|Generates| ReportJSON
    Correlator -->|Reports to| User

    style SkillTracker fill:#e1f5ff
    style WETracker fill:#fff4e1
    style Correlator fill:#f3e5ff
    style SessionID fill:#ffe1e1
```

## Data Flow

```mermaid
sequenceDiagram
    participant User
    participant SkillTracker
    participant OW as Oneiric Workflow
    participant WETracker as Workflow Event Tracker
    participant Correlator as Correlator
    participant Storage as Local Storage

    Note over User,Storage: Skill Invocation Flow
    User->>SkillTracker: track_skill("crj-run", "daily")
    SkillTracker->>Storage: Create SkillInvocation
    SkillTracker-->>User: completer function

    Note over User,Storage: Oneiric Workflow Execution
    User->>OW: python -m crackerjack run
    OW->>WETracker: workflow_started("crackerjack")
    OW->>OW: Execute fast_hooks
    OW->>WETracker: node_started("fast_hooks")
    OW->>WETracker: node_completed("fast_hooks")
    OW->>OW: Execute tests
    OW->>WETracker: node_started("tests")
    OW->>WETracker: node_completed("tests")
    OW->>WETracker: workflow_completed()
    WETracker->>Storage: Persist events

    Note over User,Storage: Skill Completion
    User->>SkillTracker: complete(completed=True)
    SkillTracker->>Storage: Update SkillInvocation
    SkillTracker->>Storage: Calculate duration

    Note over User,Storage: Correlation
    User->>Correlator: correlate_by_session()
    Correlator->>Storage: Load skill_metrics.json
    Correlator->>Storage: Load workflow_events.json
    Correlator->>Correlator: Group by session_id
    Correlator->>Correlator: Compute metrics
    Correlator-->>User: Correlation report
```

## System Boundaries

```mermaid
graph LR
    subgraph "Skills Domain - Interactive"
        ST[Skill Metrics Tracker]
        SI[SkillInvocation]
        SM[SkillMetrics]

        ST --> SI
        ST --> SM
    end

    subgraph "Oneiric Domain - Automated"
        WET[Workflow Event Tracker]
        WE[WorkflowEvent]
        DAG[Workflow DAG]

        WET --> WE
        DAG --> WET
    end

    subgraph "Correlation Domain - Analytics"
        SC[Skills-Workflow Correlator]
        CS[CorrelatedSession]

        SC --> CS
    end

    subgraph "Shared Boundary"
        Session[session_id]
        Storage[Local JSON Files]
    end

    SI -->|tags with| Session
    WE -->|tags with| Session

    SI -->|persists to| Storage
    WE -->|persists to| Storage

    Session -.->|correlation key| SC
    Storage -.->|data source| SC

    style ST fill:#e1f5ff
    style WET fill:#fff4e1
    style SC fill:#f3e5ff
    style Session fill:#ffe1e1
```

## Event Timeline

```mermaid
timeline
    title Combined Skills & Workflow Execution Timeline
    section Session abc123
        Skill Invoked : track_skill("crj-run", "daily") : 10:00:00
        Workflow Start : workflow_started("crackerjack") : 10:00:01
        Fast Hooks : node_started("fast_hooks") : 10:00:02
        Fast Hooks Done : node_completed("fast_hooks") : 10:00:07
        Tests : node_started("tests") : 10:00:08
        Tests Done : node_completed("tests") : 10:01:30
        Comprehensive : node_started("comprehensive") : 10:01:31
        Comprehensive Done : node_completed("comprehensive") : 10:02:15
        Workflow End : workflow_completed() : 10:02:16
        Skill Complete : complete(completed=True) : 10:02:20
```

## Integration Patterns

```mermaid
graph TB
    subgraph "Pattern 1: Independent Tracking"
        ST1[Skill Tracker]
        WT1[Workflow Tracker]
        ST1 -.->|No runtime dependency| WT1
    end

    subgraph "Pattern 2: Session Correlation"
        ST2[Skill Tracker]
        WT2[Workflow Tracker]
        Corr2[Correlator]
        ST2 -->|Emits with session_id| Corr2
        WT2 -->|Emits with session_id| Corr2
    end

    subgraph "Pattern 3: On-Demand Analysis"
        Events[Stored Events]
        Corr3[Correlator]
        Report[Analysis Report]

        Events -.->|Lazy load| Corr3
        Corr3 -->|Generates| Report
    end

    style Corr2 fill:#f3e5ff
    style Corr3 fill:#f3e5ff
```
