porthole/@PLAN.md

@PLAN — ControlTower (Go TUI) parallel build plan

This file breaks the project into independent, parallel tasks that multiple agents can implement with minimal merge conflicts.

• Source spec: PLAN.md
• Sub-agent models to use:
  • anthropic/claude-haiku-4-5-20251001
  • github-copilot/claude-haiku-4.5

0) Ground rules (so work composes cleanly)

0.1 File ownership

Each task below “owns” a set of files. Agents should only modify files they own, except for the explicit shared-contract files listed next.

0.2 Shared contracts (edit carefully)

These files are the primary integration points; keep them stable and coordinate changes:

• internal/model/issue.go (Issue model + enums)
• internal/collectors/collector.go (collector interface + status)
• cmd/controltower/main.go (wiring + flags)

0.3 Go module + imports

• Use standard package layout from PLAN.md.
• No persistence; acknowledgements are in-memory only.
• Prefer small packages with narrow responsibilities.

1) Proposed repo layout (target)

• cmd/controltower/main.go
• internal/model/ (Issue + enums)
• internal/store/ (IssueStore)
• internal/engine/ (scheduler + concurrency)
• internal/collectors/collector.go (shared interface)
• internal/collectors/host/ (disk.go, mem.go, load.go, net.go)
• internal/collectors/k8s/ (client.go, informers.go, issues_*.go, rollup.go, unreachable.go)
• internal/ui/ (app.go, table.go, details.go, keys.go, styles.go)
• internal/export/json.go

2) Integration contracts (must align across tasks)

2.1 Issue model contract

internal/model.Issue must support (per PLAN.md):

• Stable ID for dedupe
• Category, Priority, State enums
• Title, Details, Evidence (key/value), SuggestedFix
• FirstSeen, LastSeen

Sorting defaults:

• Priority desc → LastSeen desc (recency)

2.2 Collector contract

Create internal/collectors/collector.go with:

• type Collector interface { Name() string; Interval() time.Duration; Collect(ctx context.Context) ([]model.Issue, Status, error) }
• type Status describing health (OK/Degraded/Error + message + last success time)

Collectors should:

• Be fast; respect context cancellation.
• Return issues that are “currently true” for this tick (the store handles resolve-after).

2.3 Store contract

IssueStore.Upsert(now, issues):

• Dedupes by Issue.ID
• Tracks FirstSeen/LastSeen
• Maintains State (Open/Acknowledged/Resolved)
• Resolves only after resolveAfter (default 30s) of absence

Ack/unack should be in-memory and keyed by Issue ID.

2.4 Engine contract

Engine runs all collectors concurrently on their intervals with timeouts:

• Host collectors: collector_timeout_fast (250ms)
• K8s list/poll: collector_timeout_k8s_list (2s)

Engine produces periodic snapshots for UI/export:

• []model.Issue sorted per default
• Collector health summary (Host OK / K8s OK/DEGRADED)

3) Task breakdown (parallelizable)

Each task includes: scope, owned files, external dependencies, and acceptance checks.

Task A — Project scaffold + wiring (1 agent)

Goal: create runnable binary, shared contracts, and minimal plumbing.

• Owns:
  • go.mod, go.sum
  • cmd/controltower/main.go
  • internal/collectors/collector.go
  • (Optional) internal/buildinfo/ or version constants
• Provides:
  • CLI flag --export /path/issues.json (calls exporter and exits)
  • Default config constants (refresh interval 1s, resolveAfter 30s, timeouts)
  • K8s enabled only if kubeconfig exists (per spec)
• Must not implement heavy logic from other tasks; stub as needed.

Acceptance: go test ./... passes; go run ./cmd/controltower starts.

---

Task B — Core model package (1 agent)

Goal: implement the type system used everywhere.

• Owns:
  • internal/model/issue.go (+ small helper files if needed)
• Implements:
  • Enums: Category, Priority, State (stringers / JSON marshal if needed)
  • Issue struct + helpers:
    • func (p Priority) Weight() int (for sorting)
    • func (i Issue) Age(now time.Time) time.Duration
    • func SortIssuesDefault([]Issue)
• Evidence representation: map[string]string (simple, JSON-friendly).

Acceptance: unit tests for sorting + JSON marshalling (if added).

---

Task C — IssueStore (1 agent)

Goal: dedupe, state transitions, resolve-after, flap suppression.

• Owns:
  • internal/store/store.go
  • internal/store/store_test.go
• Needs:
  • resolveAfter default 30s
  • Flap suppression: don’t resolve on a single missed tick
  • Acknowledge(id), Unack(id) (in-memory only)
  • Snapshot() returning issues (optionally copy to avoid races)

Acceptance: tests covering:

• Dedup and timestamp updates
• Ack persists while issue present
• Resolve-after triggers only after absence window

---

Task D — Engine scheduler (1 agent)

Goal: concurrency orchestration + snapshot publication.

• Owns:
  • internal/engine/engine.go
  • internal/engine/engine_test.go
• Integrates:
  • Collectors from Task E (host) and Task F (k8s)
  • Store from Task C
  • Produces:
    • periodic snapshots (channel or callback) for UI
    • immediate refresh on demand (key r)
• Concurrency:
  • Run collectors on their own tickers
  • Per-collector context timeouts
  • Track last error/health per collector

Acceptance: deterministic tests with fake collectors verifying:

• timeout handling
• interval scheduling
• merge/upsert calls

---

Task E — Host collectors MVP (1–2 agents)

Split into sub-tasks to avoid conflicts:

E1 Disk collector

• Owns: internal/collectors/host/disk.go (+ tests)
• Reads /proc/mounts, uses statfs.
• Filters pseudo filesystems.
• Thresholds:
  • P1 if usage or inode usage ≥ 92%
  • P0 if ≥ 98%

E2 Memory + swap collector

• Owns: internal/collectors/host/mem.go (+ tests)
• Reads /proc/meminfo.
• Applies thresholds in PLAN.md.

E3 Load collector

• Owns: internal/collectors/host/load.go (+ tests)
• Reads /proc/loadavg + CPU count.
• Sustained windows: track 120s rolling window.

E4 Network collector

• Owns: internal/collectors/host/net.go (+ tests)
• Reads /proc/net/route for default route.
• Reads /sys/class/net/*/operstate for “any UP”.
• P1 if no default route AND any non-loopback UP.

Acceptance: each collector has unit tests using fixture files or temp fakes.

---

Task F — Kubernetes collector MVP (2 agents recommended)

This is the largest area; split by responsibility.

F1 K8s client + connectivity + unreachable grace

• Owns:
  • internal/collectors/k8s/client.go
  • internal/collectors/k8s/unreachable.go
• Responsibilities:
  • Build client-go config from kubeconfig current context.
  • Connectivity tracking: emit Kubernetes/P0 only after 10s continuous failure.
  • RBAC errors: emit single P2 “Insufficient RBAC …” issue per resource.

F2 Informers / polling fallback + issue rules + rollups

• Owns:
  • internal/collectors/k8s/informers.go
  • internal/collectors/k8s/issues_pods.go
  • internal/collectors/k8s/issues_nodes.go
  • internal/collectors/k8s/issues_workloads.go
  • internal/collectors/k8s/issues_events.go
  • internal/collectors/k8s/rollup.go
• Responsibilities:
  • Prefer informers (LIST+WATCH caches).
  • If watch fails repeatedly, degrade to periodic LIST and emit a P1 degraded issue.
  • High-signal rules per PLAN.md.
  • Rollups:
    • group by (namespace, reason, kind)
    • if group size ≥ 20 emit rollup issue with samples
  • Cap: k8s.max_issues = 200 after rollups.

Acceptance:

• Unit tests for rule functions (pure logic tests with fake objects)
• Manual run against a cluster (optional) verifies unreachable grace.

---

Task G — Bubble Tea TUI (2 agents recommended)

Split UI work to reduce merge conflicts.

G1 App model + layout framing

• Owns:
  • internal/ui/app.go
  • internal/ui/styles.go
• Responsibilities:
  • Header bar (host/time/age/P0..P3 counts/collector health)
  • Layout: header + table + details pane
  • Wiring to engine snapshot updates (tea.Msg)

G2 Table + details + keybindings

• Owns:
  • internal/ui/table.go
  • internal/ui/details.go
  • internal/ui/keys.go
• Responsibilities:
  • Main table columns: Pri | Cat | Title | Age | State
  • Search /, filter p/c, sort s, focus tab
  • Ack/unack a
  • Optional: Expand details with enter

Acceptance:

• UI runs and remains responsive with 1k synthetic issues.

---

Task H — Exporter (1 agent)

Goal: JSON snapshot export, no persistence.

• Owns:
  • internal/export/json.go
• Implements:
  • WriteIssues(path string, issues []model.Issue) error
  • Used by --export and (optional) UI hotkey E

Acceptance: --export writes valid JSON and exits 0.

---

Task I — End-to-end integration pass (1 agent)

Goal: compose all pieces, fix mismatches, and ensure acceptance criteria.

• Owns (only light edits across packages):
  • small wiring fixes in cmd/controltower/main.go
  • integration tweaks in engine/UI
• Validates:
  • Without kubeconfig: app runs, host collectors work
  • With kubeconfig but unreachable cluster: P0 appears only after 10s
  • With reachable cluster: issues populate; rollups protect UI

4) 8-agent assignment (recommended)

This assignment uses exactly 8 agents and keeps overlaps minimal. For each agent, you can use either model:

• anthropic/claude-haiku-4-5-20251001
• github-copilot/claude-haiku-4.5

Phase 1 (parallel, no blocking): Agents 1–6

• Agent 1 (Scaffold/contracts): Task A
• Agent 2 (Model): Task B
• Agent 3 (Store): Task C
• Agent 4 (Engine): Task D
• Agent 5 (Host collectors): Task E1–E4 (own all internal/collectors/host/*)
• Agent 6 (Exporter): Task H

Phase 2 (parallel, after A+B exist): Agents 7–8

• Agent 7 (Kubernetes collector): Task F1 + F2 (own all internal/collectors/k8s/*)
• Agent 8 (TUI + integration): Task G1 + G2 + Task I (UI owns internal/ui/*; integration touches wiring only)

Notes:

• Agent 5 is bundled intentionally to avoid conflicts in internal/collectors/host/.
• K8s (Agent 7) is bundled intentionally to avoid informer/client contract churn.
• UI + integration (Agent 8) is bundled so UI/engine message types stay aligned.

Start order (min waiting):

• Start Agents 1–6 immediately.
• Start Agents 7–8 once Agent 1 has created go.mod + internal/collectors/collector.go and Agent 2 has created internal/model/issue.go (so imports compile).

Merge order (min conflicts / keep build green):

1. Agent 1 (scaffold/contracts) — establishes module + shared interfaces
2. Agent 2 (model) — unblocks compilation for most packages
3. Agent 3 (store) + Agent 6 (export) — mostly isolated, compile-time checks
4. Agent 4 (engine) — depends on store/model/contracts
5. Agent 5 (host collectors) — depends on model/contracts; can land anytime after (1,2)
6. Agent 7 (k8s) — depends on model/contracts; may need go.sum updates
7. Agent 8 (UI + integration) — land last; touches wiring and stabilizes API edges

If you use a single shared branch:

• Prefer merging frequently in the above order and rebasing lagging work onto the latest main.
• If a shared contract must change, have Agent 1 do the change and notify all other agents.

5) Suggested agent prompts (copy/paste)

Use each prompt with model anthropic/claude-haiku-4-5-20251001 or github-copilot/claude-haiku-4.5.

Prompt template

• Implement only the task scope.
• Touch only owned files.
• Add small unit tests where indicated.
• Keep APIs aligned with the shared contracts.

Agent prompt: Task B (model)

"Implement internal/model/issue.go per @PLAN.md §2.1. Add sorting helpers and minimal tests. Do not modify other packages."

Agent prompt: Task C (store)

"Implement internal/store IssueStore with dedupe, ack/unack, resolve-after (30s), flap suppression, and tests. Import and use internal/model."

Agent prompt: Task D (engine)

"Implement internal/engine scheduler running collectors concurrently with per-collector timeouts and health tracking. Provide snapshot publication for UI; add tests with fake collectors."

Agent prompt: Task E1–E4 (host collectors)

"Implement the specified host collector in internal/collectors/host/*.go reading Linux proc/sys files as described. Emit Issues with correct IDs/evidence/priority and add small tests using fixtures/mocks."

Agent prompt: Task F1 (k8s base)

"Implement kubeconfig client creation and unreachable grace logic. Emit a single P0 issue only after 10s continuous failure; emit P2 on RBAC denial. Keep rule logic separate."

Agent prompt: Task F2 (k8s rules + rollups)

"Implement informer/polling collector and rule + rollup logic with caps. Keep rule functions testable. Coordinate only via shared contracts."

Agent prompt: Task G1/G2 (UI)

"Implement Bubble Tea UI pieces per @PLAN.md: header/table/details/keybindings. Subscribe to engine snapshots and keep rendering cheap."

Agent prompt: Task H (export)

"Implement JSON exporter used by --export and optional UI hotkey. Ensure output includes all Issue fields."

Agent prompt: Task I (integration)

"Integrate all packages, resolve API mismatches, and verify acceptance scenarios. Keep changes minimal and avoid refactors."

Agent prompt: Task J (Help overlay)

"Implement in-app help overlay showing all keybindings. Add ? key binding in keys.go and create help.go with overlay model and render logic."

Agent prompt: Task K (Direct priority jump)

"Add numeric bindings 0/1/2/3 to jump directly to P0/P1/P2/P3 filter. Keep p cycle for all."

Agent prompt: Task L (Visual filter indicators)

"Add highlighted style for active filters in header. Apply FilterActive style when pri= or cat= are set."

Agent prompt: Task M (Better empty state)

"Show friendly message 'All systems healthy' when no issues instead of just 'No issues'."

Agent prompt: Task N (Bulk ack all visible)

"Add A key to acknowledge all currently visible issues at once. Optimize updates and refresh counts."

Agent prompt: Task O (Page navigation)

"Document page up/down keys already supported by bubbles/table. Ensure they work correctly in Update handler."

Agent prompt: Task P (Home/End jump)

"Add g/G bindings to jump to first/last row quickly like vim/less."

Agent prompt: Task Q (Vi-style nav)

"Add j/k bindings as alternatives to arrow keys for down/up navigation."

Agent prompt: Task R (Collector health icons)

"Replace text 'ok=1 deg=0 err=Z' with visual icons (✓ ⚠ ✗). Use lipgloss styles."

Agent prompt: Task S (Issue count warning near cap)

"Add warning indicator in header when approaching 200-issue cap (show at >= 180)."

Agent prompt: Task T (Copy to clipboard)

"Add y key to copy SuggestedFix (or Title) to system clipboard. Add atotto/clipboard dependency."

Agent prompt: Task U (Dynamic column width)

"Add t key to toggle between compact and wide Title column widths for long issue titles."

Agent prompt: Task V (Age format toggle)

"Add d key to toggle between compact (2dm) and relative (2m ago) age formats."

Agent prompt: Task W (Rollup drill-down)

"When rollup issue selected, show 'Affected Issues' list with sample IDs in details pane."

Agent prompt: Task X (Light/dark theme toggle)

"Add T key to toggle between light and dark themes. Define two theme sets in styles.go."

Agent prompt: Task Y (Sound/flash on new P0)

"Add terminal bell/flash when P0 count increases (new critical issue detected). Respect NO_BELL env var."

Agent prompt: Task Z (Theme, sound, flash)

"Add theme toggle (T) and P0 alert (bell/flash) with env var support. Test with NO_BELL=1."

6) Definition of done

• Meets PLAN.md Acceptance Criteria.
• go test ./... passes.
• go run ./cmd/controltower works without kubeconfig.
• With kubeconfig and unreachable cluster: P0 only after 10s.
• UI remains responsive under high issue counts (rollups + caps).

7) TUI UX Improvements

This section defines UX enhancements that improve discoverability, navigation efficiency, and visual clarity. Tasks are designed for parallel agent execution (independent file ownership).

7.1 Quick wins (high-impact, low-effort)

Task J — Help overlay

Goal: Users can discover all keybindings in-app without external docs.

Agent: 1 (can be same agent that implements Task J in Phase 2)

Owned files:

• internal/ui/help.go (new)
• internal/ui/keys.go (add Help binding, update prompts)
• internal/ui/app.go (add help model + view routing)

Implementation:

• Add Help key binding (?) to KeyMap
• Create help.go with a Model struct:
  • List of keybindings by group (Global, Filters, Navigation, Actions)
  • render() function to display as overlay
• Add helpRequestedMsg type in app.go to trigger help overlay
• Update keys.go: add Help binding with help text
• Update app.go:
  • Add showHelp bool field to Model
  • Handle ? key: toggle help overlay (hide table/details)
  • Update View() to conditionally show help instead of main layout

Acceptance:

• Press ? shows keybinding list overlay covering main layout
• Press ? again or esc dismisses help
• go test ./... passes

---

Task K — Direct priority jump (0/1/2/3)

Goal: Jump directly to P0/P1/P2/P3 filter instead of cycling through all 5 options.

Agent: 1

Owned files:

• internal/ui/keys.go (add numeric bindings)
• internal/ui/app.go (update Update handler)

Implementation:

• Add bindings in keys.go:
  • PriorityP0: key.NewBinding(key.WithKeys("0"), key.WithHelp("0", "P0 only"))
  • PriorityP1: key.NewBinding(key.WithKeys("1"), key.WithHelp("1", "P1 only"))
  • PriorityP2: key.NewBinding(key.WithKeys("2"), key.WithHelp("2", "P2 only"))
  • PriorityP3: key.NewBinding(key.WithKeys("3"), key.WithHelp("3", "P3 only"))
• Update app.go Update handler:
  • Match keyMatch(msg, m.keys.PriorityP0) → set m.filterPri = model.PriorityP0
  • Match keyMatch(msg, m.keys.PriorityP1) → set m.filterPri = model.PriorityP1
  • Match keyMatch(msg, m.keys.PriorityP2) → set m.filterPri = model.PriorityP2
  • Match keyMatch(msg, m.keys.PriorityP3) → set m.filterPri = model.PriorityP3
  • Keep existing p cycle behavior for all option

Acceptance:

• Pressing 0 shows only P0 issues; 1 shows only P1, etc.
• Pressing p cycles through: all → P0 → P1 → P2 → P3 → all → …

---

Task L — Visual filter indicators

Goal: Make active filters visually obvious in header (highlight vs. plain text).

Agent: 1

Owned files:

• internal/ui/styles.go (add filter highlight style)
• internal/ui/app.go (update renderHeader())

Implementation:

• Add style in styles.go:
  • FilterActive lipgloss.Style (e.g., bold + distinct foreground)
• Update renderHeader() in app.go:
  • Apply FilterActive style to pri= or cat= portions when filter is active
  • Keep all in plain HeaderVal style

Acceptance:

• pri=P1 or cat=Kubernetes appears highlighted/colored in header
• pri=all or cat=all appears in plain text

---

Task M — Better empty state

Goal: When no issues, show helpful message instead of just “No issues”.

Agent: 1

Owned files:

• internal/ui/app.go (update applyViewFromSnapshot())

Implementation:

• In applyViewFromSnapshot() (around row building), when len(filtered) == 0:
  • Set details content to friendly message: “All systems healthy. No issues detected.”
  • Optionally: add hint like “Press r to refresh, / to search past logs”

Acceptance:

• When snapshot has 0 issues, details pane shows friendly message
• Header still displays correct P0/P1/P2/P3 counts (all 0)

---

Task N — Bulk ack all visible

Goal: Allow user to acknowledge all currently visible issues at once.

Agent: 1

Owned files:

• internal/ui/keys.go (add bulk ack binding)
• internal/ui/app.go (add AckAllVisible() method + handler)

Implementation:

• Add binding in keys.go:
  • AckAll: key.NewBinding(key.WithKeys("A"), key.WithHelp("A", "ack all visible")) (shift+a)
• Add method in app.go:
  • func (m *Model) AckAllVisible()
  • Iterate over m.rowsIDs, call m.ack(id) for each
  • Optimistically update issueByID and table rows
• Update Update() handler:
  • Match keyMatch(msg, m.keys.AckAll) → call m.AckAllVisible()

Acceptance:

• Pressing A acknowledges all issues currently visible in table
• Header P0/P1/P2/P3 counts remain correct
• a still toggles ack/unack for single selected issue

---

7.2 Navigation efficiency improvements

Task O — Page navigation (PgUp/PgDn or Ctrl+u/Ctrl+d)

Goal: Faster scrolling through long issue lists (200+ issues with rollups).

Agent: 1

Owned files:

• internal/ui/table.go (no changes needed; bubbles/table supports page keys by default)

Implementation:

• Bubbles/table already supports standard page keys:
  • pgup/pgdn
  • ctrl+u/ctrl+d
  • home/end
• Ensure these are not overridden in app.go Update handler
• Optionally: update help overlay to document these keys

Acceptance:

• PageUp/PageDown jumps 10 rows in table
• Ctrl+u/Ctrl+d jumps half a screen
• Home/End jump to top/bottom

---

Task P — Home/End jump (g/G like vim/less)

Goal: Jump to first or last row quickly.

Agent: 1

Owned files:

• internal/ui/keys.go (add bindings)
• internal/ui/app.go (add handlers)

Implementation:

• Add bindings in keys.go:
  • JumpToTop: key.NewBinding(key.WithKeys("g"), key.WithHelp("g", "jump to first"))
  • JumpToBottom: key.NewBinding(key.WithKeys("G"), key.WithHelp("G", "jump to last"))
• Update app.go:
  • Handle JumpToTop → set cursor to 0
  • Handle JumpToBottom → set cursor to last row

Acceptance:

• Pressing g moves selection to first visible row
• Pressing G moves selection to last visible row

---

Task Q — Vi-style nav (j/k in addition to arrows)

Goal: Support vim-style navigation for users who prefer hjkl.

Agent: 1

Owned files:

• internal/ui/keys.go (add bindings)
• internal/ui/app.go (add handlers)

Implementation:

• Add bindings in keys.go:
  • Down: key.NewBinding(key.WithKeys("j"), key.WithHelp("j", "down"))
  • Up: key.NewBinding(key.WithKeys("k"), key.WithHelp("k", "up"))
• Update app.go:
  • Match Down and pass to m.table.Update(msg) (bubbles/table handles both arrows and j/k)
• Update help overlay to document j/k as alternatives to arrows

Acceptance:

• j moves selection down, k moves up
• Arrows continue to work (both styles supported)

---

7.3 Visual polish & feedback

Task R — Collector health icons

Goal: Replace text “ok=1 deg=0 err=Z” with visual status icons.

Agent: 1

Owned files:

• internal/ui/app.go (update renderHeader())
• internal/ui/styles.go (add icon styles if desired)

Implementation:

• Update renderHeader() health display:
  • Use icon instead of text:
    • ✓ for OK
    • ⚠ for DEGRADED
    • ✗ for ERROR
  • Format: collectors: ✓1 ⚠0 ✗0
• Optional: use lipgloss.SetGlyphWidth() if icons appear misaligned

Acceptance:

• Header shows icon-based collector health (e.g., collectors: ✓4)
• Status still readable for screen readers (icons are supplementary)

---

Task S — Issue count warning near cap

Goal: Warn users when approaching the 200-issue cap (after rollups).

Agent: 1

Owned files:

• internal/ui/app.go (update renderHeader())

Implementation:

• In renderHeader(), calculate total issues: total := p0 + p1 + p2 + p3
• If total >= 180 (90% of cap):
  • Append warning text to collector health line: [~180/200]
  • Use warning color from styles.Error
• Only show when near cap; don’t clutter at low counts

Acceptance:

• When near 200 issues, header shows warning indicator
• Below 180 issues, no warning appears

---

Task T — Copy to clipboard (y on selected issue)

Goal: Quick copy of issue ID, Title, or SuggestedFix.

Agent: 1

Owned files:

• internal/ui/keys.go (add binding)
• internal/ui/app.go (add handler + clipboard dep if needed)
• go.mod (add clipboard dependency)

Implementation:

• Add binding in keys.go:
  • Copy: key.NewBinding(key.WithKeys("y"), key.WithHelp("y", "copy to clipboard"))
• Add dependency in go.mod (pick one):
  • github.com/atotto/clipboard (cross-platform, widely used)
  • or use xclip/xsel via exec.Command for linux-only (no new dep)
• Update app.go:
  • On y key, copy selected issue’s SuggestedFix to clipboard (most useful field)
  • Show brief confirmation in details pane: “Copied to clipboard”

Acceptance:

• Pressing y copies SuggestedFix (or Title) to system clipboard
• Brief confirmation shown in details pane

---

7.4 Nice-to-have (higher effort)

Task U — Dynamic column width

Goal: Allow widening Title column on demand for long issue titles.

Agent: 1

Owned files:

• internal/ui/keys.go (add toggle binding)
• internal/ui/app.go (add wideTitle state + update layout())

Implementation:

• Add binding in keys.go:
  • ToggleWideTitle: key.NewBinding(key.WithKeys("t"), key.WithHelp("t", "toggle wide title"))
• Add wideTitle bool field to Model
• Update layout() to compute two widths:
  • Normal mode: compact Title width (current behavior)
  • Wide mode: allocate more space to Title column
• On t toggle, recompute layout and rebuild rows

Acceptance:

• Pressing t expands Title column
• Pressing t again returns to compact width
• Header shows current state (e.g., wide=on or icon)

---

Task V — Age format toggle (compact vs. “X ago”)

Goal: Switch between “2dm” (compact) and “2m ago” (relative) formats.

Agent: 1

Owned files:

• internal/ui/keys.go (add toggle binding)
• internal/ui/app.go (add ageMode field + update rendering)

Implementation:

• Add binding in keys.go:
  • ToggleAgeFormat: key.NewBinding(key.WithKeys("d"), key.WithHelp("d", "toggle age format"))
• Add ageMode AgeMode field to Model with values: AgeCompact (default), AgeRelative
• Update table.go formatAge() or app.go wrapper to support both modes
• In renderHeader(), keep compact age (0s, Xds, Xdm, Xdh, Xdd)
• In details pane, show full time with relative suffix

Acceptance:

• Default: table shows 2dm, details shows “2m ago”
• Press d: table shows 2m ago, details show same
• Press d again: revert to compact

---

Task W — Rollup drill-down in details

Goal: When a rollup issue is selected, show the individual issues it aggregates.

Agent: 1

Owned files:

• internal/ui/model (add rollup-specific types) — or keep minimal
• internal/ui/app.go (update renderIssueDetails() / setDetailsToSelected())

Implementation:

• Add helper getRollupSamples(iss model.Issue) []string:
  • Parse iss.Evidence["samples"] if it exists
  • Return list of affected IDs/pod names
• Update renderIssueDetails() in details.go:
  • Detect rollup (e.g., ID starts with k8s:rollup: or category=Kubernetes + “rollup” in title)
  • Append section: Affected Issues with list of sample IDs (up to 10)
• Keep full rollup summary (count, namespace, reason)

Acceptance:

• Selecting a rollup issue shows “Affected Issues: [k8s:pod:default/x, k8s:pod:default/y, …]” in details
• Non-rollup issues show normal details without this section

---

Task X — Light/dark theme toggle

Goal: Respect user’s theme preference or allow toggling.

Agent: 1

Owned files:

• internal/ui/styles.go (add theme variants)
• internal/ui/keys.go (add toggle binding)
• internal/ui/app.go (add theme state)
• cmd/controltower/main.go (optional env var support)

Implementation:

• Define two theme sets in styles.go:
  • LightTheme (current hardcoded colors)
  • DarkTheme (inverted/better contrast)
• Add themeMode ThemeMode field to Model (ThemeAuto, ThemeLight, ThemeDark)
• Add binding in keys.go:
  • ToggleTheme: key.NewBinding(key.WithKeys("T"), key.WithHelp("T", "toggle theme"))
• Optional: respect NO_COLOR=1 env var (disable all colors)
• On theme toggle, update styles := defaultStyles() to apply selected theme

Acceptance:

• Default theme is current (light-like)
• Pressing T toggles light/dark
• NO_COLOR=1 disables colors entirely

---

Task Y — Sound/flash on new P0

Goal: Alert user when critical issues appear.

Agent: 1

Owned files:

• internal/ui/app.go (track P0 count changes + trigger alert)

Implementation:

• Add lastP0Count int field to Model
• In applyViewFromSnapshot():
  • Compare p0 with m.lastP0Count
  • If p0 > m.lastP0Count: new critical issues appeared
  • Update m.lastP0Count = p0
• Add alert function:
  • Use bubbletea’s bell (terminal bell) or flash:
    • Send tea.BellMsg on P0 increase
  • Optional: check for NO_BELL=1 env var to disable

Acceptance:

• When P0 count increases, terminal bell/flash occurs (if not disabled)
• P0 decrease or no change does not trigger alert
• NO_BELL=1 env var suppresses all alerts

---

8-agent assignment for UX tasks

To keep parallelism and avoid conflicts, assign as follows (can be done in Phase 3):

Agent	Tasks	Owned Files	Notes
Agent 9	Task J (Help overlay)	internal/ui/help.go, keys.go, app.go	High discoverability impact
Agent 10	Tasks K, L, M (Priority jump, visual filters, empty state)	keys.go, styles.go, app.go	Quick navigation wins
Agent 11	Tasks N, O, P (Bulk ack, page nav, home/end)	keys.go, app.go	Nav efficiency
Agent 12	Tasks Q, R (Vi nav, collector health icons)	keys.go, app.go, styles.go	Nav + visual polish
Agent 13	Tasks S, T, V (Count warning, copy clipboard, dynamic width)	keys.go, app.go, go.mod, table.go	Polish + utility
Agent 14	Tasks W, X (Rollup drill-down, age toggle)	app.go, details.go, keys.go	Details enhancements
Agent 15	Tasks Y, Z (Theme, sound/flash)	styles.go, app.go, keys.go	Theme + alerts

Execution order (minimal dependencies):

1. Agents 9–12 run in parallel (all are independent file changes)
2. Agents 13–14 run after 9–12 (may reference new keys/styles)
3. Agent 15 runs after 13–14 (may reference theme from styles)

---

8-agent assignment (UX improvements, parallel)

Agent	Tasks	Owned Files	Notes
Agent 9	Task J (Help overlay)	internal/ui/help.go, keys.go, app.go	High discoverability impact
Agent 10	Tasks K, L, M (Priority jump, visual filters, empty state)	keys.go, styles.go, app.go	Quick navigation wins
Agent 11	Tasks N, O, P (Bulk ack, page nav, home/end)	keys.go, app.go	Nav efficiency
Agent 12	Tasks Q, R (Vi nav, collector health icons)	keys.go, app.go, styles.go	Nav + visual polish
Agent 13	Tasks S, T, V (Count warning, copy clipboard, dynamic width)	keys.go, app.go, go.mod, table.go	Polish + utility
Agent 14	Tasks W, X (Rollup drill-down, age toggle)	app.go, details.go, keys.go	Details enhancements
Agent 15	Tasks Y, Z (Theme, sound/flash)	styles.go, app.go, keys.go	Theme + alerts

Execution order (minimal dependencies):

1. Agents 9–12 run in parallel (all are independent file changes)
2. Agents 13–14 run after 9–12 (may reference new keys/styles)
3. Agent 15 runs after 13–14 (may reference theme from styles)

Coordinated changes:

• keys.go is shared across Agents 9–15; each agent appends new bindings without removing others.
• app.go is shared; each agent adds new handlers in disjoint methods to avoid merge conflicts.
• styles.go is shared; agents add new styles without modifying existing.
• details.go is shared; Agents 13–14 add optional sections.
• help.go is new (Task J) and owned entirely by Agent 9.

Agent prompt: Task J (Help overlay)

"Implement in-app help overlay showing all keybindings. Add ? key in keys.go, create help.go with Model + render() function. Toggle overlay with ? key and dismiss with ? or esc."

Agent prompt: Task K (Direct priority jump)

"Add numeric bindings 0/1/2/3 in keys.go to jump directly to P0/P1/P2/P3. Keep p cycle for all option. Update app.go Update handler."

Agent prompt: Task L (Visual filter indicators)

"Add FilterActive style in styles.go (highlight color). Update renderHeader() to apply when pri= or cat= filters are active."

Agent prompt: Task M (Better empty state)

"Show friendly message 'All systems healthy' in applyViewFromSnapshot() when len(filtered) == 0."

Agent prompt: Task N (Bulk ack all visible)

"Add AckAll binding (shift+a) in keys.go. Implement AckAllVisible() method in app.go that iterates rowsIDs and calls ack(). Update handler."

Agent prompt: Task O (Page navigation)

"Document that bubbles/table supports page keys (pgup/pgdn, ctrl+u/ctrl+d). Ensure they are not overridden in app.go Update handler. Add to help overlay."

Agent prompt: Task P (Home/End jump)

"Add g/G bindings in keys.go. Add handlers in app.go: g sets cursor to 0, G sets cursor to last row. Add to help overlay."

Agent prompt: Task Q (Vi-style nav)

"Add j/k bindings in keys.go. Update app.go to pass to table.Update(); bubbles/table handles both arrows and j/k. Update help overlay."

Agent prompt: Task R (Collector health icons)

"Update renderHeader() to use icons (✓ for OK, ⚠ for DEGRADED, ✗ for ERROR) instead of text. Format: 'collectors: ✓1 ⚠0 ✗0'."

Agent prompt: Task S (Issue count warning near cap)

"In renderHeader(), calculate total issues. If total >= 180, append warning '[~180/200]' with error color. Show only when near cap."

Agent prompt: Task T (Copy to clipboard)

"Add y binding in keys.go. Add atotto/clipboard to go.mod. On y key, copy selected issue's SuggestedFix to clipboard. Show brief confirmation in details."

Agent prompt: Task U (Dynamic column width)

"Add ToggleWideTitle binding (t) in keys.go. Add wideTitle bool to Model. Update layout() to compute wide vs compact widths. Toggle with t key. Update help overlay."

Agent prompt: Task V (Age format toggle)

"Add ToggleAgeFormat binding (d) in keys.go. Add AgeMode field (Compact/Relative) to Model. Update formatAge() or wrapper in app.go to support both modes. Toggle with d key."

Agent prompt: Task W (Rollup drill-down)

"Add getRollupSamples() helper to parse Evidence['samples']. Update renderIssueDetails() in details.go to detect rollup and append 'Affected Issues' section with sample IDs."

Agent prompt: Task X (Light/dark theme toggle)

"Define LightTheme and DarkTheme in styles.go. Add themeMode field to Model with Auto/Light/Dark. Add ToggleTheme binding (T) in keys.go. Respect NO_COLOR env var."

Agent prompt: Task Y (Sound/flash on new P0)

"Add lastP0Count to Model. In applyViewFromSnapshot(), compare p0 with lastP0Count. If p0 increases, send bubbletea.BellMsg. Check NO_BELL env var."

Agent prompt: Task Z (Theme, sound, flash)

"Combine Task X (theme toggle) and Task Y (P0 alert). Test theme toggle works and P0 bell/flash. Add env var checks for NO_BELL."