AI Workforce — Admin UX PRD

Status	Owner	Last updated
Proposed (needs human greenlight)	Josh	2026-05-15

Scope: refinements to the existing AI Workforce admin views (AIWorkforceView, EmployeeDetailView, RunDetailView, ReviewQueueView). Not a new command-center page. Implementation is downstream — when greenlit, this becomes a Multica issue assigned to Maggie for routing.

1. Problem framing

The AI Workforce admin UI is functionally complete: an operator can see employees, trigger runs, approve artifacts, and inspect run details. What it does not yet do well:

1. Communicate governance state with prominence. Budget, autonomy level, and pause reason are all rendered, but they read as decoration rather than as the primary signal an operator should anchor on. When something goes wrong — runaway cost, stuck run, paused employee — the operator has to hunt.
2. Show temporal flow. Today, EmployeeDetailView has separate tabs for Overview / Runs / Memory. The reality of operating an AI employee is interleaved: a run finishes → an artifact is approved → memory is updated. The tabs make that flow invisible.
3. Use a consistent status vocabulary. Run statuses (queued/running/succeeded/failed/cancelled) and artifact statuses (pending/approved/rejected) are rendered with per-view inline-styled badges. Operators have to translate between view dialects.

We've evaluated two adjacent agent platforms — Multica and Paperclip — and want to borrow specific surface patterns from each.

2. Non-goals

• No new command-center page. The existing four views are the right shape; this PRD refines them.
• No org-chart view. Multica's routing hierarchy (Maggie → specialists) is an implicit structure, not a UI tree. Replicating it as a visual org chart in our admin would be redundant.
• No public-facing surface. AI Workforce is admin-only.
• No new tables, models, or backend endpoints unless explicitly called out below. Backend additions are surfaced as out-of-scope follow-ups.

3. Borrowed from Paperclip — governance prominence

3.1 Budget pill in card header (in addition to the existing bar)

Today: AIWorkforceView.vue:246–263 renders a progress bar with $X.YZ / $W.QR text below the card body. The bar is informative but visually demoted.

Proposed: Promote the $X.YZ / $W.QR text to the card header row, alongside the status badge. The bar stays as a secondary visual. Color the pill amber at ≥80% utilization and red at 100% — matches the existing budgetBarClass helper.

Why: Paperclip teaches that monthly spend is the single most-consequential operational signal, and it deserves header real estate. Today an operator has to scan the bottom of every card to know what they're spending.

3.2 Fleet-level aggregate banner

Today: No fleet-level view of total monthly spend.

Proposed: Above the employee card grid in AIWorkforceView, add a one-line banner: "Fleet — $X.YZ spent / $W.QR budgeted this month · N employees active · 1 paused (budget exhausted)". The "1 paused" segment links to a filter that scopes the grid.

Why: Operators currently have no way to see total workforce spend without summing visually. Paperclip's dashboard surfaces this as the first thing you see; adopting it gives us the same posture.

3.3 Auto-pause as a first-class card state

Today: Workstream 1 of the budget-enforcement plan adds a Paused — Budget exhausted red pill, distinct from the amber Paused (operator-initiated) pill. The Resume button is already present.

Proposed: Extend the red-pill state to include an inline reason line: "Paused — budget exhausted on 2026-05-12 ($30.00 / $30.00). Resumes automatically on 2026-06-01." The Resume button becomes a one-click override. Reuse PermissionGuard so only manage_ai_employees can resume.

Why: Paperclip distinguishes "paused by operator" from "auto-paused by guardrail" at the surface level. We have the data; we should surface the distinction.

3.4 Mission breadcrumb on EmployeeDetailView hero

Today: EmployeeDetailView hero shows name, role, autonomy level. No connection to product mission.

Proposed: Add a one-line excerpt under the hero: "Serves: Help people stay consistent with what matters to them." (sourced from MISSION.md's tagline or first sentence). Static for v1 — same line for every employee.

Why: Workstream 2 injects MISSION.md into every system prompt. Surfacing the same line in the UI closes the loop: the operator and the agent see the same north star.

4. Borrowed from Multica — temporal coherence

4.1 Unified "Activity" tab on EmployeeDetailView

Today: EmployeeDetailView.vue:453–491 exposes Overview / Runs / Memory tabs. Three separate lists, three separate mental contexts.

Proposed: Add a fourth tab — Activity — that interleaves the three streams chronologically:

2026-05-13 14:22  ✓ Run #4129 succeeded (2.4k tokens, $0.04)
2026-05-13 14:23  ⊕ Memory updated — key=brand-voice-context
2026-05-13 14:25  ✓ Artifact approved — Blog draft: "Streaks > Goals"
2026-05-13 09:00  ⊙ Run #4129 started (scheduled)
2026-05-12 14:22  ✓ Run #4117 succeeded
2026-05-12 14:22  ✗ Artifact rejected — Brand voice: too generic

Each row is a link to the relevant detail view. Default tab stays Overview; Activity is opt-in.

Why: Multica organizes work by issue, which means everything related to that work is on one page. Translating the metaphor: everything related to one employee belongs on one timeline.

4.2 Consistent status vocabulary via a shared badge primitive

Today: Status badges are defined inline per view:

• AIWorkforceView.vue:75–84 — employee status (active/paused, autonomy level)
• AIWorkforceView.vue:93–98 — last run status
• EmployeeDetailView — run + artifact statuses (per its own template)
• RunDetailView, ReviewQueueView — same again

Proposed: Extract a single <WorkforceStatusBadge variant="run|artifact|employee" :status="status" /> component in admin_dashboard/src/components/. One color/label mapping, used everywhere. Status vocabulary documented in the component file.

Why: Multica's strength is that "in_review" looks the same wherever it appears. Our equivalent is to make succeeded, approved, paused etc. visually identical across all four views.

4.3 Stalled-run indicator

Today: A card with active=true and a next_run_at in the distant past looks no different from a healthy card.

Proposed: On AIWorkforceView cards, if active=true AND next_run_at < now() - 1h AND no run is in flight, show an amber "Stalled" pill in the metadata area. Mirrors Multica's stalled-issue sweep concept and gives operators a passive signal that schedule drift has happened.

Why: Schedule drift is the silent failure mode of cron-driven systems. Surfacing it visually reduces the time-to-detection from "next time the operator manually checks" to "next time they open the page."

5. Visual primitives already in place

This PRD relies on existing primitives — no new visual language is being introduced.

Primitive	Reference
Status badge styling	AIWorkforceView.vue:75–84
Budget progress bar	AIWorkforceView.vue:247–263
Stat card grid	RunDetailView.vue:125–143
Tab pattern	EmployeeDetailView.vue:453–491
Vertical timeline	RunDetailView.vue:160–187
Modal dialogs	EmployeeDetailView.vue:829–858
Permission gating	admin_dashboard/src/components/PermissionGuard.vue

6. Out-of-scope follow-ups

These are explicitly not part of this PRD; flagged so they aren't forgotten.

1. Auto-resume cron. When an employee is auto-paused at budget exhaustion, today an operator must click Resume. A scheduled job on the 1st of each month should re-activate any employee that was auto-paused for budget reasons.
2. Fleet-level hard cap. Per-employee budgets sum to a workspace total. We may want a workspace-level cap that hard-rejects all runs once crossed, regardless of individual budgets.
3. Employee template library. Paperclip's "Cliphub" surfaces shareable agent templates. Out of scope for now — our crew is curated, not user-generated.
4. Cost-per-artifact breakdown. A drill-down from total spend → which artifacts cost what. Useful, but not in v1.
5. Multi-currency / non-USD budgets. Cents-USD is hardcoded; future surface if we operate in multiple currencies.

7. Implementation sequencing (when greenlit)

This PRD becomes one or more Multica issues. Suggested split:

1. Issue 1 — Shared status badge. Extract WorkforceStatusBadge, replace inline badges across all four views. (4.2)
2. Issue 2 — Budget prominence. Header pill + fleet banner + auto-pause reason line. (3.1, 3.2, 3.3)
3. Issue 3 — Mission breadcrumb. Single line on EmployeeDetailView. (3.4)
4. Issue 4 — Activity tab. New tab on EmployeeDetailView with interleaved timeline. (4.1)
5. Issue 5 — Stalled-run pill. Conditional pill on AIWorkforceView. (4.3)

Each issue is independently shippable. Recommended order: 1 → 2 → 5 → 3 → 4 (smallest blast radius first).

8. Open questions

• Should the fleet banner be filterable (active only, autonomy level, etc.), or just a static summary?
• Should the Activity tab paginate beyond N rows, or just truncate at "last 50 events"?
• Should the mission breadcrumb be editable per-employee in the future (e.g., a mission_focus field), or remain global?

Answers can wait for issue-level planning.

---

Last updated: 2026-05-15