Hub Status System — Design Spec

Date: 2026-07-23 Status: Approved direction; layout decisions delegated to Claude (best practices) Builds on: 2026-07-23-unicorn-land-hub-design.md

Problem

The hub currently mirrors the file tree. Joshua works sporadically across ~25 projects; most have no status captured anywhere, so the hub can’t answer “where does this stand and what’s next.” A prettier file browser doesn’t fix that — the missing thing is a status layer kept current as a byproduct of working.

Decisions (from brainstorming)

• Primary lens: project status — where each project stands + the next action.
• Capture trigger: automatic at the end of every session (a standing convention Claude follows; interaction stays via Claude Code / Discord).
• Item structure: structured & lightweight — title + state (+ optional owner).

The status object

Each project carries a STATUS.md at its root: YAML frontmatter (the structured, machine-read part) + optional markdown body (freeform narrative). Backward compatible with the existing freeform STATUS.md files — we just add frontmatter above the prose.

---
project: Bold Little Oracle
state: active            # idea · active · blocked · paused · shipped
summary: "1.1.0 in App Review after replying to the iPad rejection."
next_action: "Await Apple approval, then ship iPhone-only fix."
updated: 2026-07-23
items:
  - title: "Apple approves 1.1.0 bug-fix submission"
    state: waiting-external
  - title: "Confirm next build ships supportsTablet:false"
    state: todo
    owner: claude
  - title: "Decide whether to retire the overnight worktree"
    state: waiting-you
---

Project states: idea · active · blocked · paused · shipped Item states: todo · waiting-you · waiting-external · done Fields: project (display name), state, summary (one line), next_action, updated (date), items[] (each: title, state, optional owner).

All fields optional except a project should at least have state + summary to be “tracked.” Missing/invalid frontmatter → project shows as untracked (visible but flagged), never a build error.

Rendering — the command center

Landing page becomes a command center, not a recent-files list:

1. Attention bar (top): big rollup numbers — N waiting on you, active, blocked, todo — computed across all projects. Answers “what needs me” at a glance.
2. Needs you: projects that are blocked, or have any waiting-you items, surfaced first with their next action and the specific waiting items.
3. By state: remaining projects grouped active → paused → idea → shipped. Each is a status card: state chip, name, one-line summary, next action (prominent), item counts (e.g. “2 todo · 1 waiting”), updated date + staleness flag (⚠ if active/ blocked and untouched > 21 days).
4. Untracked: muted section listing projects with no valid STATUS frontmatter (doc count + “needs a status” hint) so they’re never invisible.

Per-project page (new <project>/index.html): a status panel at the top — state chip, summary, next action, items as a checklist with per-state chips (todo ○ · waiting-you ● · waiting-external ⏳ · done ✓), updated — then the STATUS.md narrative body, then the project’s document list. Command-center cards link here.

Individual doc pages keep the existing rendering; they become secondary (reachable from the project page and sidebar), not the main event.

Capture ritual (the process)

• Standing convention in ~/.claude/CLAUDE.md (global) + project CLAUDE.mds: every session that meaningfully changes a project under ~/Projects ends by updating that project’s STATUS.md — set state, summary, next_action, updated, and reconcile items (mark done, add new todos, flip waiting states). Status is a byproduct of work.
• Discord capture: a stray thought → appended to the right project’s items as a todo (owner defaults to you unless it’s clearly a Claude task).
• Safety net (optional, deferred): a Stop hook that reminds when a session edited a project but left its STATUS.md untouched. Convention first; hook later if it slips.

Implementation

• Extend hub/build.py: parse STATUS.md frontmatter (PyYAML), compute rollups + staleness, render the command center + per-project pages. Doc rendering unchanged.
• hub/STATUS.template.md: the canonical template + field docs.
• Seed real STATUS.md frontmatter for projects Claude has genuine knowledge of (bold-little-oracle, the hub itself, the ventures). Do not fabricate status for dormant/unknown projects — they render as “untracked” until a session gives them one.
• Add the capture convention to ~/.claude/CLAUDE.md and Unicorn.Land/CLAUDE.md.
• make hub rebuilds + redeploys behind the existing Cloudflare Access gate.

Non-goals

Due dates, priorities, dependencies, assignees beyond owner, a database, or any UI that writes back. Capture stays in Claude Code / Discord; the hub is read-only.