Timmy-time-dashboard/docs/adr/023-workshop-presence-schema.md

ADR-023: Workshop Presence Schema

Status: Accepted Date: 2026-03-18 Issue: #265 Epic: #222 (The Workshop)

Context

The Workshop renders Timmy as a living presence in a 3D world. It needs to know what Timmy is doing right now — his working memory, not his full identity or history. This schema defines the contract between Timmy (writer) and the Workshop (reader).

The Tower IS the Workshop

The 3D world renderer lives in the-matrix/ within token-gated-economy, served at /tower by the API server (artifacts/api-server). This is the canonical Workshop scene — not a generic Matrix visualization. All Workshop phase issues (#361, #362, #363) target that codebase. No separate alexanderwhitestone.com scaffold is needed until production deploy.

The workshop-state spec (#360) is consumed by the API server via a file-watch mechanism, bridging Timmy's presence into the 3D scene.

Design principles:

• Working memory, not long-term memory. Present tense only.
• Written as side effect of work. Not a separate obligation.
• Liveness is mandatory. Stale = "not home," shown honestly.
• Schema is the contract. Keep it minimal and stable.

Decision

File Location

~/.timmy/presence.json

JSON chosen over YAML for predictable parsing by both Python and JavaScript (the Workshop frontend). The Workshop reads this file via the WebSocket bridge (#243) or polls it directly during development.

Schema (v1)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Timmy Presence State",
  "description": "Working memory surface for the Workshop renderer",
  "type": "object",
  "required": ["version", "liveness", "current_focus"],
  "properties": {
    "version": {
      "type": "integer",
      "const": 1,
      "description": "Schema version for forward compatibility"
    },
    "liveness": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp of last update. If stale (>5min), Timmy is not home."
    },
    "current_focus": {
      "type": "string",
      "description": "One sentence: what Timmy is doing right now. Empty string = idle."
    },
    "active_threads": {
      "type": "array",
      "maxItems": 10,
      "description": "Current work items Timmy is tracking",
      "items": {
        "type": "object",
        "required": ["type", "ref", "status"],
        "properties": {
          "type": {
            "type": "string",
            "enum": ["pr_review", "issue", "conversation", "research", "thinking"]
          },
          "ref": {
            "type": "string",
            "description": "Reference identifier (issue #, PR #, topic name)"
          },
          "status": {
            "type": "string",
            "enum": ["active", "idle", "blocked", "completed"]
          }
        }
      }
    },
    "recent_events": {
      "type": "array",
      "maxItems": 20,
      "description": "Recent events, newest first. Capped at 20.",
      "items": {
        "type": "object",
        "required": ["timestamp", "event"],
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "event": {
            "type": "string",
            "description": "Brief description of what happened"
          }
        }
      }
    },
    "concerns": {
      "type": "array",
      "maxItems": 5,
      "description": "Things Timmy is uncertain or worried about. Flat list, no severity.",
      "items": {
        "type": "string"
      }
    },
    "mood": {
      "type": "string",
      "enum": ["focused", "exploring", "uncertain", "excited", "tired", "idle"],
      "description": "Emotional texture for the Workshop to render. Optional."
    }
  }
}

Example

{
  "version": 1,
  "liveness": "2026-03-18T21:47:12Z",
  "current_focus": "Reviewing PR #267 — stream adapter for Gitea webhooks",
  "active_threads": [
    {"type": "pr_review", "ref": "#267", "status": "active"},
    {"type": "issue", "ref": "#239", "status": "idle"},
    {"type": "conversation", "ref": "hermes-consultation", "status": "idle"}
  ],
  "recent_events": [
    {"timestamp": "2026-03-18T21:45:00Z", "event": "Completed PR review for #265"},
    {"timestamp": "2026-03-18T21:30:00Z", "event": "Filed issue #268 — flaky test in sensory loop"}
  ],
  "concerns": [
    "WebSocket reconnection logic feels brittle",
    "Not sure the barks system handles uncertainty well yet"
  ],
  "mood": "focused"
}

Design Answers

Question	Answer
File format	JSON (predictable for JS + Python, no YAML parser needed in browser)
recent_events cap	20 entries max, oldest dropped
concerns severity	Flat list, no priority. Keep it simple.
File location	~/.timmy/presence.json — accessible to Workshop via bridge
Staleness threshold	5 minutes without liveness update = "not home"
mood field	Optional. Workshop can render visual cues (color, animation)

Consequences

• Timmy's agent loop must write ~/.timmy/presence.json as a side effect of work. This is a hook at the end of each cycle, not a daemon.
• The Workshop frontend reads this file and renders accordingly. Stale liveness → dim the wizard, show "away" state.
• The WebSocket bridge (#243) watches this file and pushes changes to connected Workshop clients.
• Schema is versioned. Breaking changes increment the version field. Workshop must handle unknown versions gracefully (show raw data or "unknown state").

Related

• #222 — Workshop epic
• #243 — WebSocket bridge (transports this state)
• #239 — Sensory loop (feeds into state)
• #242 — 3D world (consumes this state for rendering)
• #246 — Confidence as visible trait (mood field serves this)
• #360 — Workshop-state spec (consumed by API via file-watch)
• #361, #362, #363 — Workshop phase issues (target the-matrix/)
• #372 — The Tower IS the Workshop (canonical connection)