hermes/automaton
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
48d8fb4f446ffbcc25cb151c1ddf06d1064461e2
automaton/tasks/dashboard-spec.md
T

9.7 KiB
Raw Blame History

Contract: Interactive Dashboard for Automaton Framework

Goal

Build an interactive terminal dashboard that visualizes and monitors task progress within the automaton framework. The dashboard is scope-aware: when opened in ~/.automaton/, it tracks framework development tasks; when opened in any project root (a project that has installed automaton), it tracks that project's tasks.

Requirements

1. Scope-Aware Context Detection

  • 1.1 The dashboard detects its scope by walking up the directory tree from the current working directory to find the nearest .automaton/ folder.
  • 1.2 If the nearest .automaton/ folder is ~/.automaton/, the dashboard operates in framework mode (tracks framework development).
  • 1.3 If the nearest .automaton/ folder is inside a project root, the dashboard operates in project mode (tracks that project's tasks).
  • 1.4 The current scope is displayed in the dashboard header.

2. Kanban Board View (Primary View)

  • 2.1 The board displays tasks as cards organized into columns by their current phase.
  • 2.2 Columns map directly to the automaton task state machine:
    • Backlog — No artifacts (New state)
    • Research — Has SPEC.md (Research phase)
    • Decomposition — Has SPEC.md + DECOMPOSITION.md (Decomposition phase)
    • Design — Has SPEC.md + DESIGN.md (Design phase)
    • Implement — Has IMPLEMENTATION.md (Implement phase)
    • Bug Find — Has BUG_REPORT.md (Bug Find phase)
    • Adversarial Bug Find — Has ADVERSARIAL_BUG_REPORT.md (Adversarial Bug Find phase)
    • Doc Review — Has DOC_REVIEW.md (Doc Review phase)
    • Referee — Has VERDICT.md (Referee phase)
    • Done — VERDICT.md with PASS (Complete state)
    • Blocked — VERDICT.md with FAIL or NEEDS_REVIEW (Human Intervention)
  • 2.3 Tasks with sub-tasks show a collapsed indicator (e.g., [3/5]) showing sub-task completion progress.
  • 2.4 Tasks can be expanded to show sub-task details inline.
  • 2.5 Columns are horizontally scrollable if they overflow the terminal width.

3. Task Cards

  • 3.1 Each task card displays:
    • Task name (kebab-case folder name, human-readable)
    • Current phase/column
    • Time elapsed since task creation (if timestamp is available)
    • Sub-task progress indicator (if applicable)
    • Status indicator (e.g., ✅ PASS, ❌ FAIL, ⏸ BLOCKED, 🔄 IN PROGRESS)
  • 3.2 Cards are selectable with arrow keys or mouse.
  • 3.3 Selected card shows expanded details in a side panel or bottom panel.

4. Task Detail Panel

  • 4.1 When a task card is selected, the detail panel shows:
    • Full task name and folder path
    • Current state/mapping to kanban column
    • List of artifacts present (SPEC.md, DESIGN.md, etc.) with status
    • Sub-task list (if applicable) with individual statuses
    • VERDICT.md content (if present)
    • BUG_REPORT.md content (if present)
  • 4.2 The detail panel is resizable.
  • 4.3 Navigating away from a task hides the detail panel.

5. Statistics View

  • 5.1 A statistics view accessible via keybinding shows:
    • Total tasks count
    • Tasks per phase breakdown (bar chart or table)
    • Pass/Fail/Blocked rate
    • Average tasks completed per day (if timestamps available)
    • Current WIP (tasks in progress, not in Backlog or Done)
  • 5.2 Statistics are calculated in real-time from the tasks/ directory.

6. Timeline View

  • 6.1 A timeline view accessible via keybinding shows:
    • Tasks arranged by their progress through phases over time
    • Wave visualization for decomposed tasks (Wave 1, Wave 2, etc.)
    • Sub-task parallel execution visualization
  • 6.2 Timeline is scrollable and zoomable.

7. Filtering and Search

  • 7.1 Filter tasks by phase/status using a filter bar.
  • 7.2 Filter tasks by sub-task wave (for decomposed tasks).
  • 7.3 Search tasks by name using a search bar.
  • 7.4 Filters are combinable (e.g., show only "Research" tasks in Wave 2).

8. Keyboard Navigation

  • 8.1 Arrow keys to move between columns and cards.
  • 8.2 Enter to expand/collapse selected card or view task details.
  • 8.3 Space to cycle through views (Board → Statistics → Timeline).
  • 8.4 q or Ctrl+C to quit.
  • 8.5 ? to show keybindings help.
  • 8.6 f to open filter bar.
  • 8.7 s to open search bar.
  • 8.8 w to cycle through waves (for decomposed tasks).

9. Auto-Refresh

  • 9.1 The dashboard auto-refreshes when the tasks/ directory changes (file system watch).
  • 9.2 Auto-refresh interval: 2 seconds (configurable).
  • 9.3 Manual refresh triggered by r key.
  • 9.4 Refresh indicator in the header shows when a refresh occurs.

10. Configuration

  • 10.1 Dashboard settings stored in {project}/.automaton/dashboard-config.json:
    • auto_refresh_interval: seconds between auto-refreshes (default: 2)
    • default_view: which view to show on startup ("board", "statistics", "timeline")
    • column_width: minimum width of each column in characters (default: 30)
    • show_timelines: show time elapsed on cards (default: true)
    • theme: color theme ("default", "dark", "light")
  • 10.2 Configuration is scoped to the project (not global).

11. Color Theme

  • 11.1 Default theme uses ANSI color codes for:
    • Backlog: gray
    • Research: blue
    • Decomposition: purple
    • Design: cyan
    • Implement: green
    • Bug Find: orange
    • Adversarial Bug Find: red (darker)
    • Doc Review: yellow
    • Referee: magenta
    • Done: green (bright)
    • Blocked: red
  • 11.2 Theme is switchable via keybinding (t to cycle themes).

12. Sub-Task Visualization

  • 12.1 For decomposed tasks, sub-tasks are shown as indented items under the parent task card.
  • 12.2 Sub-task progress is shown as a fraction (e.g., [3/5] = 3 of 5 sub-tasks complete).
  • 12.3 Clicking a sub-task shows its detail in the detail panel.
  • 12.4 Sub-task waves are visualized with visual separation in the Timeline view.

13. Performance

  • 13.1 Dashboard renders within 500ms of a refresh (for projects with up to 100 tasks).
  • 13.2 No blocking I/O during rendering.
  • 13.3 File system watch uses inotify (Linux) or kqueue (macOS) for efficient change detection.

14. Error Handling

  • 14.1 If tasks/ directory is missing, show a "No tasks found" message.
  • 14.2 If a task artifact file is corrupted or unreadable, show a warning indicator on the card.
  • 14.3 If the dashboard is opened outside any automaton project, show an error and exit gracefully.

15. Documentation

  • 15.1 README.md in the dashboard module with usage instructions.
  • 15.2 Keybindings reference accessible via ? in the dashboard.
  • 15.3 Configuration schema documented with default values.

Non-Goals

  • 15.1 Web UI (browser-based) — this is terminal-only (TUI).
  • 15.2 Real-time collaboration — single-user only.
  • 15.3 Task creation/editing — dashboard is read-only for task state.
  • 15.4 Notification system — no push notifications or alerts.
  • 15.5 Calendar integration — no date-based scheduling.
  • 15.6 Integration with external PM tools — standalone only.

Acceptance Criteria

  • Dashboard detects scope (framework vs. project) correctly based on cwd
  • Board view displays all tasks in correct Kanban columns based on state machine
  • Task cards show name, phase, status, and sub-task progress
  • Task detail panel shows full task information when selected
  • Statistics view shows correct counts per phase and pass/fail rates
  • Timeline view shows task progress and wave structure
  • Filter bar filters tasks by phase and wave
  • Search bar finds tasks by name
  • All 11 keyboard bindings (Enter, Space, q, ?, f, s, w, t, r) work correctly
  • Auto-refresh works on file system changes with 2-second interval
  • Dashboard configuration file is created and read correctly
  • Color themes cycle correctly with 3 themes
  • Sub-task visualization shows progress fraction and expandable details
  • Dashboard renders within 500ms for 100 tasks
  • Error handling works for missing tasks/ directory and corrupted artifacts
  • Documentation includes usage instructions and keybindings reference

Risks & Mitigations

  • Risk 1: Terminal rendering performance degrades with many tasks
    • Mitigation: Implement virtual rendering (only render visible columns/cards), lazy-load task details
  • Risk 2: File system watch conflicts with agent writing artifacts
    • Mitigation: Use debounced file system events, handle partial writes gracefully
  • Risk 3: Task state determination is inconsistent with Orchestrator
    • Mitigation: Use the same state machine logic as orchestrate.md for determining task states
  • Risk 4: Dashboard breaks when automaton framework is upgraded
    • Mitigation: Dashboard reads state from the same artifacts the Orchestrator reads; no hardcoded state machine logic — it derives from artifact presence

Notes

  • The dashboard should be a separate module under ~/.automaton/ (e.g., ~/.automaton/dashboard/) so it can be upgraded independently.
  • The dashboard uses the same layered file system approach as the Orchestrator — it reads from project's .automaton/ first, then falls back to global ~/.automaton/.
  • Task names in the dashboard should be human-readable. The kebab-case folder name (e.g., add-user-auth) should be converted to a display name (e.g., "Add User Auth") by replacing hyphens with spaces and capitalizing.
  • The dashboard is a read-only view of task state — it does not modify or create artifacts. All task lifecycle operations continue through the Orchestrator.

Stop Condition

When all checkboxes are checked and the dashboard is fully functional, output "CONTRACT_MET" and stop.

Reference in New Issue View Git Blame Copy Permalink