workbench-dashboard 0.1.3__py3-none-any.whl

workbench/__init__.py

@@ -0,0 +1,3 @@
+"""Workbench: personal dashboard for software projects and learning paths."""
+
+__version__ = "0.1.3"

workbench/__main__.py

@@ -0,0 +1,3 @@
+from workbench.cli import app
+
+app()

workbench/agents/__init__.py

@@ -0,0 +1 @@
+"""Coding-agent integration: the Stop/AfterAgent hook, the headless updater, and the installer."""

workbench/agents/assets/chat/LEARNING_PROMPT.md

@@ -0,0 +1,67 @@
+# Workbench learning-path chat prompt
+
+Paste everything below the line into the chat that holds what you have been learning. Replace the
+CURRENT OUTLINE placeholder first:
+
+- existing path: the output of `workbench learning export <path-id>`
+- new path: `NEW: <Path Name>`
+
+Save the reply's outline as a `.md` file and run `workbench learning import <file>.md`. Importing
+into an existing path merges: statuses only move forward, and items missing from the outline are
+kept, so progress marked on the dashboard is never lost.
+
+---
+
+Turn what this conversation shows about my learning into a Workbench learning-path outline: what I
+set out to learn, what I have covered, what I am partway through, and what is still left. The "still
+left" part matters most; do not skip it.
+
+CURRENT OUTLINE:
+<paste `workbench learning export <path-id>` output here, or write NEW: <Path Name>>
+
+Reply with exactly one ```markdown code block and nothing else — no text before or after it.
+
+FORMAT:
+
+```markdown
+# Control Theory
+Feedback control from first principles, aimed at steering a field robot along crop rows.
+- [Feedback Systems by Astrom and Murray](https://fbswiki.org/wiki/index.php/Main_Page)
+
+## [x] Linear systems
+State-space models and what decides whether a system settles.
+
+### [x] State-space models
+Writing dynamics as x' = Ax + Bu.
+
+### [~] Stability and eigenvalues
+Eigenvalues of A in the left half-plane mean the system settles.
+
+## [ ] PID control
+The controller used on the robot's steering loop.
+
+### [ ] Tuning
+Choosing gains from a step response.
+
+### [ ] Anti-windup
+Stopping the integral term from growing while the actuator is saturated.
+```
+
+RULES:
+
+1. Structure: one `#` line with the path name, then `##` topics, each with `###` subtopics. Nothing
+   deeper than `###`.
+2. Status marker right after the hashes on every `##` and `###` line: `[x]` covered and understood,
+   `[~]` started but not finished, `[ ]` not started. Mark `[x]` only when the conversation shows I
+   actually worked through it.
+3. Keep every topic and subtopic from CURRENT OUTLINE with exactly the same heading text, including
+   any `{#id}` at the end of a heading. You may change its marker and summary, and add new items.
+   Never rename or remove one.
+4. Still left → `[ ]` items: what I said I want to learn next, prerequisites we found I am missing,
+   and topics we deferred. Do not add topics I did not ask for or agree to.
+5. Under any heading you may add one line of summary (≤300 characters; under `#`, ≤500) and links as
+   `- [Label](https://...)` lines. Labels ≤40 characters; only `https://` links. Leave them out if
+   you have nothing real to put there — never invent a link.
+6. Heading names ≤80 characters. Two items must not have the same name.
+7. Never include secrets, passwords, local file paths, email addresses, or personal information.
+8. If something is unclear from the conversation, leave it out instead of guessing.

workbench/agents/assets/chat/PROMPT.md

@@ -0,0 +1,107 @@
+# Workbench chat prompt
+
+Paste everything below the line into the chat that holds the project's history (claude.ai, the
+desktop app, or any other assistant). Replace the CURRENT ENTRY placeholder first:
+
+- existing project: the output of `workbench show --id <project-id>`
+- new project: `NEW: <Project Name>`
+
+Then put the reply into Workbench with `workbench begin --id <project-id>`: replace the printed
+`project.yaml` with the reply's YAML and run `workbench push <worktree> -m "<summary>"`. Push
+validates the format, scans for private data, and refuses removed ids.
+
+---
+
+Update my Workbench dashboard entry for the project described in this conversation. Use everything
+this conversation shows about it: what was built, what is in progress, what was decided, what is
+still failing, and what is left to do. The "left to do" part matters most; do not skip it.
+
+CURRENT ENTRY:
+<paste `workbench show --id <project-id>` output here, or write NEW: <Project Name>>
+
+Reply with exactly one ```yaml code block and nothing else — no text before or after it.
+
+FORMAT (keys in this order):
+
+```yaml
+schema_version: 1
+id: field-robotics            # keep the current id; for NEW, a slug of the name
+name: Field Robotics          # ≤80 chars
+description: >-               # ≤500 chars: what the project is and what it is for
+  Autonomous field robot for row-crop scouting: localization, navigation and mapping
+  on a ROS 2 stack, plus the tooling around it.
+status: active                # planned | active | paused | done | archived — keep current unless I said otherwise
+uses_phases: true
+repos: []                     # copy from the current entry unchanged
+links: []                     # copy unchanged; you may add {label: ≤40 chars, url: https://...}
+phases:
+  - id: localization
+    name: Localization
+    status: done              # not_started | in_progress | done | parked
+    summary: GPS plus wheel odometry fused into a single pose estimate.
+    components:
+      - id: gps-driver
+        name: GPS driver
+        status: done
+        summary: Reads RTK fixes and publishes them in the map frame.
+        components:           # optional: a component's own parts, nested to any depth
+          - id: rtk-corrections
+            name: RTK corrections
+            status: done
+            summary: Streams base-station corrections to the receiver.
+      - id: pose-fusion
+        name: Pose fusion
+        status: done
+        summary: Fuses GPS and odometry into one pose.
+        depends_on: [gps-driver]
+  - id: navigation
+    name: Navigation
+    status: in_progress
+    summary: Following crop rows and turning at headlands.
+    components:
+      - id: row-following
+        name: Row following
+        status: in_progress
+        summary: Pure-pursuit controller along detected rows.
+        notes: Overshoots at speeds above 1 m/s; gains not yet tuned in the field.
+        depends_on: [pose-fusion]
+        items:
+          - Tune lookahead distance in a field test
+      - id: headland-turns
+        name: Headland turns
+        status: not_started
+        summary: Turn-around at row ends, needed before full-field runs.
+        depends_on: [row-following]
+topics: []
+```
+
+RULES:
+
+1. Merge, do not regenerate. Keep every phase and component already in CURRENT ENTRY with the same
+   `id`; update its status and text, and add new ones. Never rename or drop an `id`. If the entry
+   uses `uses_phases: false` with `topics:` instead of `phases:`, keep that structure.
+2. Status: `done` only when it is built and working; `in_progress` when partly built or not yet
+   working; `not_started` when planned; `parked` when put on hold. A phase is `done` when all its
+   components are, `in_progress` when any has started.
+3. Left to do → `not_started` components: things I said should happen next or later, work that was
+   deferred or split off, known problems that were not fixed, and follow-ups I agreed to. Do not add
+   ideas I did not agree to.
+4. Every phase with real work — done, in progress, or planned — has components. Only a `parked` or
+   not-yet-planned phase may have none.
+5. Ids: lowercase letters, digits and single hyphens (`row-following`), at most 48 characters,
+   unique across the whole entry.
+6. `depends_on` only lists ids of other components in this entry, and must not form a cycle.
+7. `summary` ≤300 chars (what it is; for planned work, why it is needed). `notes` ≤1000 chars
+   (what is failing or blocking, and the next step). `items` is an optional checklist, each ≤300
+   chars. Leave out any optional field you have nothing for.
+8. Do not include `updated` or `origin`; Workbench sets them.
+9. Never include secrets, API keys, passwords, local file paths, email addresses, IP addresses,
+   pasted logs or error output, or personal information about anyone.
+10. If something is unclear from the conversation, leave it out instead of guessing.
+11. A component can list its own `components:` (to any depth) when it is made of smaller parts;
+    ids stay unique across the whole entry, nested ones included.
+12. If CURRENT ENTRY has `parent:` and `under:` lines, this project is a child of another project;
+    copy both unchanged. Do not add them yourself — making a project a child of another is done
+    with `workbench new "<Name>" --parent <id> --under <item-id>` or `workbench attach`, and only
+    when I ask. A project has at most one parent. Project `status: planned` means not started yet;
+    a child project shows in the Projects tab only while `active`, otherwise only inside its parent.

workbench/agents/assets/claude/workbench-review/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: workbench-review
+description: Full review of a project's Workbench dashboard entry - reconcile everything this session built, finished, and left to do. Use when a Workbench hook reminder asks for a review (after a commit), at the end of a session, when creating a new project, or when the user runs /workbench-review. For a small change after one message, use workbench-update instead.
+---
+
+# Workbench review: reconcile the whole entry
+
+This is the full, milestone update (after a commit, at the end of a session, or on request). For the
+small per-message update — one item's status, a new problem found — use the **workbench-update**
+skill instead; it is much cheaper.
+
+The project's dashboard entry (`project.yaml`) is its long-term memory: each session adds what it
+learned. You are the only one who knows what this session did, so your job is to turn this
+conversation into an accurate update — what exists now, what is half-done, and what is left to do.
+The "left to do" part is the point of the dashboard; never skip it.
+
+## Sources, in order of trust
+
+1. **This conversation** (including any compaction summary): what was built, fixed, decided,
+   deferred, what is still failing, and what the user said comes next.
+2. **The current entry** (`workbench show`): what earlier sessions recorded. Keep it unless this
+   conversation shows it is wrong or out of date.
+3. **Repo docs and code** (README, architecture/plan/progress/TODO files): only to fill an empty or
+   newly discovered entry (`phases: []` and `topics: []`), or to check a structure you are unsure of.
+
+## Which project?
+
+- **Work inside one project's git repo** (the usual case, and every Stop hook reminder): run
+  `workbench show` and `workbench begin` with no arguments from that repo; they find the project
+  from the repo itself.
+- **Work that is not in a git repo** (planning, research, hardware, chat-only sessions), **or work
+  for a project that spans several repos**, or the user names the project: pass
+  `--id <project-id>` to both `workbench show` and `workbench begin`. If unsure of the id, ask.
+- **The project does not exist yet**: create it with `workbench new "<Project Name>"` (it prints
+  the id), then use `--id`.
+- **The user wants this repo to belong to that project**: run `workbench link --id <project-id>`
+  from inside the repo. Only do this when the user asks.
+
+## Steps
+
+1. **Read the entry**: run `workbench show` (or `workbench show --id <project-id>`, see above).
+
+2. **Take stock of this conversation** as three lists:
+   - **Built / finished** — working now (tests pass, or the user saw it work) → `done`.
+   - **In progress** — started but not complete or not yet working → `in_progress`.
+   - **Left to do** — planned work → `not_started`. This counts:
+     - what the user said should happen next or later ("next we need…", "after that…", "TODO");
+     - work deferred, descoped for now, or split off during the session;
+     - known failures that were not fixed (failing tests or checks, open bugs);
+     - follow-ups you proposed that the user agreed to;
+     - recommendations from this session that are not on the dashboard yet — **ask first**: use
+       the AskUserQuestion tool with `multiSelect: true` (one option per suggestion, short label and
+       one-line description, up to 4 options per question and 4 questions), and record only the
+       ones the user selects. Without that tool, list them numbered and ask in text.
+
+     This does **not** count: unselected or declined suggestions, or speculative features you never
+     put to the user.
+
+3. **Decide whether to update**: if the three lists add nothing to the entry (pure refactor,
+   formatting, a small fix with no status change), run `workbench hook-check --mark-seen`, reply
+   `"Workbench: no update needed"`, and stop. A newly agreed next step or a newly known failure
+   **is** an update. (Outside a git repo there is nothing to mark seen; just reply and stop.)
+
+4. **Edit**: run `workbench begin` (or `workbench begin --id <project-id>`) and edit the
+   `project.yaml` path it prints. Merge — do not
+   regenerate:
+   - **Keep everything already there.** Update statuses, add new items, never rename an `id`.
+     New ids are lowercase slugs (`^[a-z0-9]+(-[a-z0-9]+)*$`), unique across the whole file.
+   - **Structure** — keep an existing `uses_phases` setting. For an empty entry, choose
+     `uses_phases: true` with `phases:` if the work runs in stages, or `uses_phases: false` with
+     `topics:` if it is a set of areas.
+   - **Every phase or topic with real work — done, in progress, or planned — gets children**
+     (`components:`, or `topics:` / `subtopics:`). A phase with only a summary shows as an empty box
+     on the dashboard. Only a `parked` or not-yet-planned phase may have no children.
+   - **Status** — child: `done` only when implemented and working; `in_progress` when partly built;
+     `not_started` when planned; `parked` when the user put it on hold. A phase follows its
+     children: `done` when all are done, `in_progress` when any has started.
+   - **`depends_on`** — list component ids a component needs first (existing ids only, no cycles).
+     Link related work wherever one item really needs another.
+   - **Build the tree, don't flatten it** — put each sub-task under the item it belongs to, so the
+     entry keeps gaining depth as work is broken down; when items already exist elsewhere in the
+     entry, link to them with `depends_on` instead of duplicating them.
+   - **Nesting** — a component can hold its own `components:` list, to any depth, for a part made of
+     smaller parts. Ids stay unique across the whole project, nested ones included.
+   - **Child projects** — a piece of work too big for one entry can be its own project. The
+     *child* carries `parent: <project-id>` and `under: <phase-or-component-id>` (an item in the
+     parent, at any depth); the parent's file is not changed. Create one with
+     `workbench new "<Name>" --parent <project-id> --under <item-id>`, or place an existing project
+     with `workbench attach --id <child> --parent <project-id> --under <item-id>`
+     (`workbench detach --id <child>` undoes it). Only do this when the user agrees. A project has
+     one parent at most. Record the child's detail in the child, not in the parent.
+   - **Text fields** — `summary` (≤300 chars): what it is; for `not_started` work, what it is and
+     why it is needed. `notes` (≤1000 chars): current state that will change — what is failing or
+     blocking, counts, the next concrete step. `items` (each ≤300 chars): optional short checklist
+     of concrete sub-tasks.
+   - **Project fields** — keep `description` (≤500 chars) a one-paragraph explanation of the
+     project. Project `status`: `planned` (not started yet), `active`, `paused`, `done`, `archived`;
+     change it only if the user said so (`workbench new --status planned` for work not begun). A
+     child project shows in the Projects tab only while `active`; otherwise it shows only inside
+     its parent. Keep `parent`/`under` as they are. Do not edit `updated` or `origin`; the CLI sets
+     them.
+   - **Learning paths** may list `related_projects: [<project-id>, ...]` — a plain reference to
+     projects the learning supports; no status flows either way.
+   - **Privacy** — never include secrets, API keys, local paths (`/Users/...`, `~/...`), emails,
+     private IPs, pasted logs or error output, or personal information.
+
+   Example of recording the future:
+   ```yaml
+   - id: mapping-path
+     name: Mapping path
+     status: in_progress
+     summary: Derivation sheets for the occupancy-grid mapping path.
+     notes: 13 of 253 sheets fail checks; inverse_sensor_model is the only failure on this path.
+     items:
+       - Fix inverse_sensor_model sheet citations
+   - id: second-project-nodes
+     name: Second project nodes
+     status: not_started
+     summary: Atlas nodes for a second project, to test the pipeline beyond one codebase.
+   ```
+
+5. **Push**: run `workbench push <worktree> -m "<one-line summary>"`. The CLI files the commit as
+   `review(<project>): <summary>`, so write only the summary.
+   - If validation or privacy checks fail, fix the file in the worktree and push again.
+   - If push reports removed ids or a large deletion, you rewrote instead of merging: restore the
+     missing items and push again. Pass `--allow-removals` only if the user explicitly asked to
+     remove something.
+
+6. **Report**: give the one-line result from `workbench push`, then list the `not_started` items you
+   recorded so the user can correct them.

workbench/agents/assets/claude/workbench-update/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: workbench-update
+description: Quick per-message update of the Workbench dashboard - record what this message changed for the one item being worked on (a status, a note, a newly found problem). Use when a Workbench hook reminder asks for a quick update, or after a message that finished, started, or broke something. For a full reconcile of the whole entry, use workbench-review.
+---
+
+# Workbench update: record this message, scoped to one item
+
+The dashboard should change a little after every message: something got done, something started,
+or a new problem turned up. This skill records **only that**, for the item this message worked on.
+Do not read or rewrite the whole entry — that is what **workbench-review** is for.
+
+Keep it to one or two commands. Each one validates, privacy-scans, commits and pushes on its own.
+
+## 1. Find the item
+
+The hook reminder usually names the current **focus** (`project` or `project/item`). If it does not,
+or this message worked on something else:
+
+```bash
+workbench focus                                 # current focus for this repo, if any
+workbench show --id <project> --brief           # one line per item: id, status, name
+workbench show --id <project> --item <item-id>  # just that item and its parts
+```
+
+Inside a project's repo `--id` can be left out. Use the ids exactly as printed.
+
+## 2. Record what changed
+
+Pick the smallest command that says it:
+
+```bash
+# something moved: done, started, parked
+workbench set <project> <item-id> --status done|in_progress|not_started|parked
+
+# the current state changed (what is failing or blocking, the next step) — replaces the notes
+workbench set <project> <item-id> --notes "Overshoots above 1 m/s; next: tune lookahead in a field test"
+
+# a new problem or a newly agreed next step — a new item under an existing phase or component
+workbench add <project> --under <item-id> --name "Fix Float timeout in rtk_sim" --status not_started \
+  --summary "rtk_sim never drops to Float, so the safety monitor's timeout cannot be tested"
+
+# link items: this one needs others first (component ids, comma-separated; set replaces the list)
+workbench add <project> --under <item-id> --name "Field coverage run" --depends-on headland-turns,safety-monitor
+workbench set <project> <item-id> --depends-on headland-turns
+```
+
+**Build the tree, don't flatten it.** A sub-task goes `--under` the item it belongs to, so items
+keep gaining children as work is broken down (a part of a part is fine, to any depth). Add a new
+top-level phase only for genuinely new work.
+
+`--name` and `--summary` can also be passed to `set`. Leave out `--under` on `add` only to create a
+new phase (or topic). Each command remembers its project/item as the focus for this repo, so the
+next reminder names it for you.
+
+## 3. Let the user pick from your suggestions
+
+If this message ended with recommendations, follow-ups, or options for the user that are not
+already on the dashboard, do not add them silently. Ask with the **AskUserQuestion** tool,
+`multiSelect: true`, one option per suggestion: a short label (1–5 words) and a one-line
+description. Use up to 4 options per question and up to 4 questions; if there are more
+suggestions, group related ones or ask about the most important.
+
+Then add **only the selected ones**, each in the right place:
+- `--under` the existing item it belongs to (check `workbench show --brief`), so the tree gains
+  depth instead of a flat list;
+- `--depends-on` the items it needs first, whether they already existed or were just selected
+  (add those first so their ids exist).
+
+Unselected suggestions were declined: do not add them. If the AskUserQuestion tool is not
+available, list the suggestions numbered, ask which to track, and wait for the answer.
+
+## 4. Or nothing
+
+If this message changed nothing worth recording (a refactor, formatting, discussion that settled
+nothing), run `workbench hook-check --mark-seen` and reply `Workbench: no update needed`.
+
+## Rules
+
+- **Statuses**: `done` only when built and working (tests pass or the user saw it work);
+  `in_progress` when partly built; `not_started` for planned work; `parked` when the user put it on hold.
+- **New items**: problems actually found, next steps the user asked for or agreed to, and
+  suggestions the user selected in step 3. Your own suggestions go through step 3, never straight in.
+- **Never** rename or remove items here; restructuring belongs in workbench-review.
+- **Privacy**: no secrets, API keys, local paths (`/Users/...`, `~/...`), emails, private IPs,
+  pasted logs or error output, or personal information.
+- Commits are filed as `update(<project>/<item>): ...` automatically.
+- Then reply with the one line each command printed.

workbench/agents/assets/gemini/GEMINI.md

@@ -0,0 +1,96 @@
+<!-- WORKBENCH:START -->
+## Workbench Project Tracking
+
+The project's Workbench entry (`project.yaml`) is its long-term memory on the dashboard. There are two
+modes. The Workbench AfterAgent hook asks for a **quick update** when files changed since the last
+update, and for a **full review** when a new commit landed; otherwise it asks for nothing.
+
+### Quick update (after each message)
+
+Record only what this message changed, for the one item it worked on. Do not read or rewrite the whole
+entry. Use one or two commands; each validates, privacy-scans, commits and pushes on its own.
+
+1. Find the item. The hook reminder usually names the current focus (`project` or `project/item`). If
+   not, or this message worked on something else:
+   ```bash
+   workbench focus                                 # current focus for this repo, if any
+   workbench show --id <project> --brief           # one line per item: id, status, name
+   workbench show --id <project> --item <item-id>  # just that item and its parts
+   ```
+   Inside a project's repo `--id` can be left out. Use the ids exactly as printed.
+2. Record what changed with the smallest command that says it:
+   ```bash
+   workbench set <project> <item-id> --status done|in_progress|not_started|parked
+   workbench set <project> <item-id> --notes "<current state and next step>"   # replaces the notes
+   workbench add <project> --under <item-id> --name "<Name>" --status not_started --summary "<why>"
+   ```
+   `set` also takes `--name` and `--summary`; `add` also takes `--id` and `--notes`. Leave out
+   `--under` on `add` only to create a new phase (or topic). Each command sets the repo's focus.
+3. Or, if this message changed nothing worth recording (refactor, formatting, discussion that settled
+   nothing), run `workbench hook-check --mark-seen` and reply "Workbench: no update needed".
+
+Rules: `done` only when built and working (tests pass or the user saw it work); `in_progress` when
+partly built; `not_started` for planned work; `parked` when the user put it on hold. New items only for
+work the user agreed to, problems actually found, or suggestions the user picked: if this message ended with suggestions not yet on the dashboard, list them numbered, ask which to track, and add only the chosen ones. Put sub-tasks --under the item they belong to so the tree keeps gaining depth; link items with --depends-on <ids>. Never rename or remove items
+here; restructuring belongs in a full review. Never include secrets, API keys, local paths, emails,
+private IPs, pasted logs or error output, or personal information. Commits are filed as
+`update(<project>/<item>): ...` automatically. Reply with the one line each command printed.
+
+### Full review (after a commit, at session end, or on request)
+
+Reconcile everything this session built, finished, and left to do. The "left to do" part is the point
+of the dashboard; never skip it. Also use this when creating a new project.
+
+Sources, in order of trust: (1) this conversation — what was built, fixed, decided, deferred, still
+failing, and what the user said comes next; (2) the current entry from `workbench show` — keep it unless
+this conversation shows it is wrong; (3) repo docs and code — only to fill an empty entry
+(`phases: []` and `topics: []`) or check a structure.
+
+Which project: inside one project's git repo, run `workbench show` / `workbench begin` with no
+arguments. For work not in a git repo (planning, research, chat-only), for a project spanning several
+repos, or when the user names the project, pass `--id <project-id>` to both (ask if unsure of the id).
+If the project does not exist yet, create it with `workbench new "<Project Name>"`. If the user wants
+the current repo to belong to that project, run `workbench link --id <project-id>` inside the repo.
+
+1. Run `workbench show` (or `workbench show --id <project-id>`).
+2. Take stock of this conversation as three lists:
+   - Built / finished (working now) → `done`.
+   - In progress (started, not complete or not working yet) → `in_progress`.
+   - Left to do → `not_started`: what the user said comes next or later, work deferred or split off,
+     known unfixed failures (failing tests or checks, open bugs), and follow-ups you proposed that the
+     user agreed to, and suggestions from this session the user picked when asked (list them numbered and ask which to track). Not unpicked suggestions or speculative features you never raised.
+3. If the lists add nothing to the entry (pure refactor, formatting, a small fix with no status change),
+   run `workbench hook-check --mark-seen`, reply "Workbench: no update needed", and stop. A newly agreed
+   next step or newly known failure is an update. (Outside a git repo, just reply and stop.)
+4. Run `workbench begin` (or `workbench begin --id <project-id>`) and edit the printed `project.yaml`.
+   Merge — do not regenerate:
+   - Keep everything already there; update statuses, add items, never rename an `id`. New ids are
+     unique lowercase slugs.
+   - Keep an existing `uses_phases` setting. For an empty entry use `uses_phases: true` with `phases:` if
+     the work runs in stages, or `uses_phases: false` with `topics:` if it is a set of areas.
+   - Every phase or topic with real work — done, in progress, or planned — gets children (`components:`,
+     or `topics:` / `subtopics:`). Only a `parked` or not-yet-planned phase may have none.
+   - Child status: `done` only when implemented and working; `in_progress` when partly built;
+     `not_started` when planned; `parked` when on hold. A phase follows its children.
+   - `depends_on` lists component ids needed first (existing ids, no cycles); link related work instead of duplicating it.
+   - Build the tree: put each sub-task under the item it belongs to, to any depth, rather than flat at the top.
+   - A component may hold its own `components:` list (any depth); ids stay unique across the project.
+   - A big piece of work can be its own child project: the child carries `parent: <project-id>` and
+     `under: <phase-or-component-id>` (an item in the parent, any depth). Only if the user agrees,
+     create it with `workbench new "<Name>" --parent <id> --under <item-id>` or place an existing one
+     with `workbench attach --id <child> --parent <id> --under <item-id>` (`workbench detach --id
+     <child>` undoes it). One parent per project; record the child's detail in the child.
+   - `summary` (≤300 chars): what it is, and for planned work why it is needed. `notes` (≤1000 chars):
+     what is failing or blocking and the next concrete step. `items`: optional short sub-task checklist.
+   - Project `status`: `planned` (not started), `active`, `paused`, `done`, `archived`; change it only
+     if the user said so. A child project shows in the Projects tab only while `active`, otherwise
+     only inside its parent. Keep `parent`/`under`. Do not edit `updated` or `origin`.
+   - Learning paths may list `related_projects: [<project-id>]` (a reference only; no status flows).
+   - Never include secrets, local paths, emails, private IPs, pasted logs, or personal information.
+5. Run `workbench push <worktree> -m "<one-line summary>"`; the CLI files the commit as
+   `review(<project>): <summary>`, so write only the summary. If validation fails, fix the file and push
+   again. If it reports removed ids or a large deletion, restore the missing items. Pass
+   `--allow-removals` only if the user explicitly asked to remove something.
+6. Report the one-line result, then list the `not_started` items you recorded so the user can correct
+   them.
+<!-- WORKBENCH:END -->

workbench/agents/assets/gemini/commands/workbench-review.toml

@@ -0,0 +1,8 @@
+description = "Full Workbench review of this project's entry"
+
+prompt = """
+Reconcile the current project's Workbench entry with this conversation by following the
+"Full review (after a commit, at session end, or on request)" section of the Workbench Project
+Tracking instructions in your GEMINI.md context: record what this session built, what is in
+progress, and what is left to do, then push with `workbench push`.
+"""

workbench/agents/assets/gemini/commands/workbench-update.toml

@@ -0,0 +1,9 @@
+description = "Quick Workbench update for what this message changed"
+
+prompt = """
+Record what this message changed in the current project's Workbench entry, scoped to the one item it
+worked on, by following the "Quick update (after each message)" section of the Workbench Project
+Tracking instructions in your GEMINI.md context: find the item with `workbench focus` or
+`workbench show --brief`, then run the smallest `workbench set` or `workbench add` command, or
+`workbench hook-check --mark-seen` if nothing changed.
+"""