From 8abc63efdbc0bb96cd6c9aa99d6e9166e0bcabae Mon Sep 17 00:00:00 2001
From: Peter Stone <thepeterstone@gmail.com>
Date: Sun, 22 Mar 2026 23:45:19 +0000
Subject: chore: unify and centralize agent configuration in .agent/

---
 .agent/ux_philosophy.md | 82 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 .agent/ux_philosophy.md

(limited to '.agent/ux_philosophy.md')

diff --git a/.agent/ux_philosophy.md b/.agent/ux_philosophy.md
new file mode 100644
index 0000000..e9b6a87
--- /dev/null
+++ b/.agent/ux_philosophy.md
@@ -0,0 +1,82 @@
+# UI/UX Review & Redesign Proposal
+
+## Current State Analysis: "The Unusable Form"
+
+The current "Quick Add" modal (in `index.html`) and the "Planning" tab form suffer from several friction points:
+
+1.  **Context Blindness:** When adding a Trello card, you must first pick a source, then a board, then a list. This is 3+ clicks before you even type the task name.
+2.  **Repetitive Data Entry:** Creating multiple related stories (e.g., across 3 repos) requires filling the entire form 3 times.
+3.  **No "Smart" Defaults:** The form doesn't remember your last used project, repo, or base image.
+4.  **Mobile Friction:** Select dropdowns are native and small, making them hard to use for long lists of repos or boards.
+5.  **Information Overload:** The "Task" and "Shopping" tabs in the modal use the same `HandleUnifiedAdd` endpoint but different fields, leading to a "leaky abstraction" in the UI.
+
+---
+
+## 1. Redesign: The "Command Palette" Model
+
+Instead of a traditional form, we should move towards a **Command Palette** style interaction (Ctrl+K).
+
+### Proposed Streamlined Flow:
+1.  **Trigger:** `Ctrl+K` opens a search-first modal.
+2.  **Type:** User types "doot: fix css in dashboard" or "claudomator: update go version".
+3.  **Prefix Detection:**
+    *   `d:` or `t:` -> Todoist task.
+    *   `tr:` -> Trello card.
+    *   `c:` or `s:` -> Claudomator Story (New).
+4.  **Contextual Suggestions:** As the user types, the bottom of the modal shows:
+    *   "Repo: doot" (detected from prefix or frequency)
+    *   "Project: Phase 6"
+    *   "Base Image: Go 1.24"
+
+---
+
+## 2. Resource Management Model (Repos, Images, Projects)
+
+The user requested a "better model for management." We should move away from flat strings and toward a **Resource Graph**.
+
+### New SQLite Schema (Internal)
+*   **`claudomator_repos`:** `id, name, remote_url, default_branch, local_path`
+*   **`claudomator_images`:** `id, name, tag, description (e.g., "Go 1.24 + Node 22")`
+*   **`claudomator_projects`:** `id, name, description`
+*   **`project_repos`:** Junction table linking projects to multiple repositories.
+
+### Management UI
+Instead of hiding these in settings, we should have a **"Library" view** (perhaps a new tab or a sub-section of Planning) where users can:
+*   Quick-add a new repo.
+*   Toggle which "Base Images" are active for selection.
+*   Group repos into "Projects" for batch operations.
+
+---
+
+## 3. UI/UX Recommendations & Plugins
+
+### Recommended Plugins/Libraries
+1.  **[Tom Select](https://tom-select.js.org/):** To replace native `<select>`. This allows for:
+    *   Searchable dropdowns (essential for 20+ repos).
+    *   Custom rendering (show repo icons/logos in the list).
+    *   Remote data loading (HTMX-friendly).
+2.  **[Alpine.js](https://alpinejs.dev/):** To handle "Local UI State" without page refreshes.
+    *   Example: Toggling between "Simple Task" and "Complex Story" modes in the same modal.
+    *   Example: Multi-select for repos.
+3.  **[Tailwind Forms Plugin](https://github.com/tailwindlabs/tailwindcss-forms):** To make inputs look professional with zero effort.
+4.  **[Lucide Icons](https://lucide.dev/):** To replace the emoji-heavy UI with cleaner, more professional SVG icons.
+
+---
+
+## 4. Proposed User Flow for Story Creation
+
+**Goal: From "Idea" to "Running Agent" in < 15 seconds.**
+
+1.  **Open Studio:** User clicks a new "Create Story" button (or `Ctrl+K` then `s`).
+2.  **Draft:** User types the goal.
+3.  **Auto-Select:** System auto-selects the "Active Project" and its associated "Primary Repo".
+4.  **Elaborate (AI):** User hits `Enter`. HTMX swaps the form for a "Thinking..." animation.
+5.  **Review Tree:** AI returns a task tree. User can click a task to edit its "Validation Spec".
+6.  **Launch:** User hits "Execute". Story moves to `IN_PROGRESS` and appears on the main dashboard.
+
+---
+
+## Next Steps (Deferred to Phase 7)
+*   Implement the SQLite migrations for the new Resource Graph.
+*   Build the "Story Studio" using Alpine.js + Tom Select.
+*   Create the management UI for Repos and Projects.
-- 
cgit v1.2.3