From 575e51eaa943cbbf65abb7de64008e4cc373fa5b Mon Sep 17 00:00:00 2001
From: "Waylon S. Walker" <waylon@waylonwalker.com>
Date: Tue, 25 Nov 2025 12:45:13 -0600
Subject: [PATCH] add readme and prompt

---
 prompt.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 readme.md | 50 ++++++++++++++++++++++++++++++++++
 2 files changed, 130 insertions(+)
 create mode 100644 prompt.md
 create mode 100644 readme.md

diff --git a/prompt.md b/prompt.md
new file mode 100644
index 0000000..bc6b7f9
--- /dev/null
+++ b/prompt.md
@@ -0,0 +1,80 @@
+Create a workspace management tool.
+
+I want a cli written to manage workspaces in a directory
+
+cli features
+
+* list workspaces
+  * workspace name
+  * workspace description (read from the readme, everything after the h1 title)
+  * included repos, with ascii/int ahead/behind/dirty indicators
+* add repos to a workspace (default workspace to current workspace)
+  * use iterfzf to pick repo
+  * list all directories in repos_dir as a repo
+  * checkout a worktree on branch with the name of the workspace into the
+    workspace with the repo_name
+* list repos and branch on a current workspace
+  * repo name (should also be directory name)
+  * use ascii/int ahead/behind/dirty indicators for git status
+* create new workspace
+  * ask for a name and description
+  * name will be the directory name
+  * make a readme with format `# <name>\n\n<description>`
+
+
+configuration
+
+* get workspaces_name from flag / settings / environment variable / default
+  WORKSPACES_DIR
+  * workspaces_name defaults to git
+  * repos_dir = ~/workspaces_name
+  * workspaces_dir = ~/workspaces_name + ".workspaces"
+* workspaces will be two sibling directories, 
+  * allow me to specify the workspaces name ex: work, personal, git, with a
+    flag to any command, fallback to env WORKSPACES_DIR, fallback to default
+  * repos_dir with all repos I work on, I will keep it clean default to ~/git
+  * workspaces_dir that I do work from that contains the workspace and a
+    collection of worktrees checked out from the repo in the repos_dir default
+    to ~/git.workspaces
+
+fuzzy picker
+
+* iterfzf is a python library that comes with fzf for fuzzy picking things
+``` python
+from iterfzf import iterfzf
+metadata = { "key": "value" }
+tables = metadata.tables.keys()
+table_name = iterfzf(tables, prompt="pick a table")
+```
+
+directory layout
+
+repos_dir
+  repo1
+  repo2
+  repo3
+  ...
+workspaces_dir
+  workspace1
+    readme.md
+    repo1 (worktree)
+    repo2 (worktree)
+  workspace2
+    readme.md
+    repo2 (worktree)
+    repo3 (worktree)
+  ...
+
+use the format for uv scripts as shown below. use typer for the cli, rich
+console and rich table for cli output, pydantic-settings for settings.
+
+#!/usr/bin/env -S uv run --quiet --script
+# /// script
+# requires-python = ">=3.12"
+# dependencies = [
+#     "typer",
+#     "rich",
+#     "pydantic",
+#     "pydantic-settings",
+# ]
+# ///
diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..a53b4d3
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,50 @@
+# Workspaces
+
+Workspaces is a workspace management tool meant to keep your cloned repos
+clean, and check out worktrees into a workspace for focused work on a task that
+would require multiple repos.
+
+
+## Usage
+
+```
+❯ alias work='/path/to/workspaces.py'
+❯ work --help
+
+ Usage: workspaces.py [OPTIONS] COMMAND [ARGS]...
+
+ Workspace management tool
+
+╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ --workspaces-name     -W      TEXT  Logical name for this workspace set (e.g. 'git', 'work', 'personal'). Overrides WORKSPACES_NAME env. Defaults to 'git'.                       │
+│ --install-completion                Install completion for the current shell.                                                                                                     │
+│ --show-completion                   Show completion for the current shell, to copy it or customize the installation.                                                              │
+│ --help                              Show this message and exit.                                                                                                                   │
+╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+╭─ Commands ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│ list         List all workspaces.                                                                                                                                                 │
+│ create       Create a new workspace.                                                                                                                                              │
+│ list-repos   List repos and branches in the current (or specified) workspace.                                                                                                     │
+│ add-repo     Add a repo to a workspace.                                                                                                                                           │
+╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```
+
+## directory layout
+
+```
+repos_dir
+  repo1
+  repo2
+  repo3
+  ...
+workspaces_dir
+  workspace1
+    readme.md
+    repo1 (worktree)
+    repo2 (worktree)
+  workspace2
+    readme.md
+    repo2 (worktree)
+    repo3 (worktree)
+  ...
+```