# Team Activity Dashboard — V1 Implementation Plan

## Goal
Ship a fast, low-risk first version of the dashboard under `/opt/pub/dashboard` with two pages:

1. **Index page** — operational overview of team progress, per-agent contributions, token totals, and status labels.
2. **Visualizer page** — a lightweight animated 90s RPG office scene showing each agent at desks, a meeting area, idle animations, and simple movement for task handoffs.

This V1 should be **static HTML/CSS/JS** with **periodic JSON refresh**. No backend app is required for the first release.

---

## V1 Architecture

### Static assets
- `index.html` — dashboard overview
- `visualizer.html` — animated office scene
- `assets/style.css` — shared styles
- `assets/app.js` — shared data loading and rendering helpers
- `assets/visualizer.js` — scene animation logic
- `data/dashboard.json` — single JSON snapshot consumed by both pages

### Update model
- A scheduled job or script writes `data/dashboard.json` on a fixed interval.
- Pages refresh via `fetch()` every 15–60 seconds.
- Use `ETag` or cache-busting query strings later if needed; for V1, simple periodic refresh is enough.

---

## Data Model

Keep the data format compact and easy to generate from A IMF agency logs.

### Top-level schema
```json
{
  "generated_at": "2026-04-29T08:30:00Z",
  "project": {
    "name": "Team Activity Dashboard",
    "phase": "V1",
    "overall_status": "in_progress",
    "progress_percent": 62
  },
  "summary": {
    "open_tasks": 5,
    "completed_tasks": 18,
    "blocked_tasks": 1,
    "token_total": 184220
  },
  "agents": [
    {
      "id": "ethan-pm",
      "name": "Ethan",
      "role": "PM / Orchestrator",
      "status": "coordinating",
      "status_label": "Coordinating",
      "tokens_used": 42310,
      "tasks_active": 2,
      "tasks_done": 7,
      "last_update": "2026-04-29T08:25:00Z",
      "current_task": "Triage latest implementation notes",
      "desk": "pm"
    }
  ],
  "tasks": [
    {
      "id": "task-12",
      "title": "Draft implementation plan",
      "owner": "luther-architect",
      "state": "in_progress",
      "priority": "high",
      "updated_at": "2026-04-29T08:20:00Z"
    }
  ],
  "events": [
    {
      "time": "2026-04-29T08:24:00Z",
      "type": "handoff",
      "from": "ethan-pm",
      "to": "grace-frontend",
      "label": "UI handoff"
    }
  ]
}
```

### Required fields per agent
- `id`
- `name`
- `role`
- `status` / `status_label`
- `tokens_used`
- `tasks_active`
- `tasks_done`
- `last_update`
- `current_task`
- `desk` position key

### Suggested status values
Use a small fixed set so the UI stays readable:
- `idle`
- `working`
- `coordinating`
- `reviewing`
- `blocked`
- `handoff`
- `offline`

### Optional fields for later
- `token_rate`
- `elapsed_task_time`
- `recent_files`
- `links` to logs or notes
- `avatar_variant`
- `movement_target`

---

## Data Sources Needed from A IMF agency / Status Logs

For V1, the dashboard only needs a few reliable inputs:

1. **Agent identity and role**
   - profile name
   - display name
   - assigned function

2. **Current status**
   - working / idle / blocked / reviewing / handoff
   - last status timestamp

3. **Task attribution**
   - active task title or short summary
   - task ownership
   - completion count if available

4. **Token usage**
   - total tokens used per agent
   - project total
   - optional token delta since last refresh

5. **Recent activity events**
   - handoffs
   - task start / task completion
   - blocker updates
   - review/approval events

### Recommended log extraction approach
- Prefer one **normalized snapshot JSON** produced from whatever A IMF agency/status logs exist.
- If the raw source is fragmented, create a small parser script later; V1 can start with a manually assembled or semi-automated snapshot.
- Do not block V1 on perfect telemetry completeness.

---

## Index Page Sections

The overview page should be information-dense but simple.

### 1) Header / project banner
- Project title
- Short subtitle
- Last refresh time
- Overall status badge
- Progress percent

### 2) KPI strip
Show 4–6 prominent cards:
- Project progress
- Total tokens
- Active agents
- Open tasks
- Blocked tasks
- Completed tasks

### 3) Per-agent contribution table
Columns:
- Agent
- Role
- Status label
- Tasks active
- Tasks done
- Tokens used
- Last update
- Current task

Use color chips for status and maybe a tiny sparkline-like bar for relative token usage.

### 4) Workboard / task snapshot
- Active tasks
- Blockers
- Recently completed items
- Latest handoffs

### 5) Activity timeline
- Reverse chronological list of notable events
- Keep only the last 10–20 entries for V1

### 6) Footer / source note
- Data source description
- Refresh interval
- Link to visualizer page

---

## Visualizer Page: Minimal But Compelling Approach

The goal is not a full game engine. It should feel alive with a few strong, cheap-to-build effects.

### Scene layout
Use a single CSS scene with layered divs:
- background office wall and floor
- desks arranged in a grid
- central meeting area / conference table
- simple props like monitors, papers, plants, and posters
- each agent represented by a sprite-like avatar card or pixel-art-style block

### Visual style
- 90s RPG office / SNES-era UI feel
- pixel-ish outlines or chunky gradients
- muted office palette with neon accent colors for statuses
- retro UI labels and window frames
- optional scanline or CRT overlay at low opacity

### Agent representation
Each agent should have:
- a desk position
- a small animated avatar
- a nameplate
- a status badge
- a tiny speech bubble or floating task label when active

### Animation set for V1
Keep it simple and deterministic:
- **Idle bob**: subtle up/down loop
- **Blink/pulse**: status light or monitor glow
- **Seat wobble / typing**: when working
- **Walk-to-handoff**: move between two desk coordinates using CSS transform transitions or requestAnimationFrame
- **Meeting cluster**: move 2–3 agents to the center meeting zone for handoff/review events

### Animation triggers from data
Use event types from the JSON snapshot:
- `task_started` → agent moves to desk and enters working state
- `handoff` → source agent walks to meeting area, then target agent receives label
- `blocked` → agent flashes amber/red and pauses
- `review` → agent stands near meeting table briefly

### Simple implementation tactic
- Render agents as absolutely positioned elements.
- Maintain `x/y` target coordinates for each agent.
- Update positions with CSS transitions.
- Use JS timers for idle animation classes.
- Reconcile state on each JSON refresh; only animate when state changes.

### Keep V1 scope tight
Do not build pathfinding, physics, collision, or game-like interaction in V1.

---

## What to Defer to Later Phases

### Defer from V1
- Live websocket updates
- Full event replay/history
- Drag-and-drop interaction
- Rich avatar customization
- Pathfinding around desks and obstacles
- Complex sprite animation sheets
- Real-time collaboration on the page
- Filtering and search across all tasks/events
- Charts beyond basic bars/sparklines
- Backend database or API if the JSON snapshot is enough

### Possible V2+ enhancements
- Animated event timeline playback
- Clicking an agent opens a detail drawer
- Heatmaps for workload and token consumption
- Historical comparisons by day/week
- Responsive mobile-specific layout
- More expressive RPG props and scene transitions

---

## Suggested Build Order

### Step 1: Define snapshot schema
- Lock the JSON shape
- Decide required vs optional fields
- Create sample data

### Step 2: Build the overview page
- Header
- KPI strip
- Agent table
- Task/activity sections

### Step 3: Build the visualizer shell
- Office layout
- Agent desk positions
- Status badges
- Idle animation

### Step 4: Add movement and handoff events
- Animate desk-to-meeting transitions
- Show simple event labels

### Step 5: Wire periodic refresh
- Poll JSON snapshot
- Re-render changed data
- Preserve animation state where possible

### Step 6: Polish
- Color tuning
- Responsive behavior
- Empty-state handling
- Loading/error states

---

## Acceptance Criteria for V1
- Index page loads successfully and shows project progress, per-agent contributions, token totals, and status labels.
- Visualizer page shows a recognizable retro office scene with each agent placed at a desk.
- Agents animate idly without user input.
- Handoff/status changes from JSON result in visible movement or state transitions.
- Page updates from a refreshed JSON snapshot without a full backend rewrite.

---

## Recommendation
For fastest delivery, start with a **single static JSON snapshot** generated from A IMF agency logs and build both pages against that contract. This gives the team a working dashboard quickly while keeping the data pipeline flexible for later automation.