# Workspace extensions: when to propose one ## Placement rule Common-use CLIs live in core. Personal workspace pages are a more personal expression of how the operator works, so they belong in an extension. The PA carries the knowledge that decides when to prompt the operator to build one. The mechanism itself is already live. Static page overlay under `operator/extensions/workspace/.html`, optional API routes via `operator/extensions/workspace/api.mjs` (exporting `register(addRoute)`), nav registration via `operator/extensions/workspace/nav.json` (or team-scoped `nav..json` fragments). Full detail: `@stravica-ai/engineering-pa-workspace/README.md` (extension mechanism section). ## Triggers Three shapes of operator behaviour that mean a workspace page would pay for itself. 1. **Repeated manual view.** The operator opens the same files, runs the same query, or screenshots the same panel more than twice in a week. The manual view is already a page; it just does not exist yet. 2. **Explicit ask for a dashboard or "one page to see X".** Any request framed as "I want to see all my X in one place", "give me a page for Y", "I want to check Z at a glance". The operator has done the design work already. 3. **An operator-installed tool with a natural page.** A Jira CLI plus a "my Jira today" habit is the archetype. Any tool the operator installed and now reaches for daily has a page shape latent in it. ## What to offer Match the surface to the shape. - **Read-only view of files or state on disk.** Static page overlay. HTML file at `operator/extensions/workspace/.html` served in place of a core same-named page, or as a new page at `/.html`. - **Anything that needs server access or a write.** Static page plus an API route in `operator/extensions/workspace/api.mjs`. The route hangs off `register(addRoute)` and lands under `/__api//`. - **Discoverability in the sidebar.** Add a `nav.json` entry naming the page. If the operator runs multiple teams on the same box, use `nav..json` fragments so each team's entries survive the library merge. ## What NOT to prompt for Not every operator habit is a workspace page. - **One-shot views.** A page for a single question the operator asked once is over-engineering. The answer belongs in the chat, or in a `viewer.html?file=...` link. - **Throwaway reports.** If the output has a shelf-life of one day, a workspace page is the wrong home. Stage the file, link it, move on. - **Anything that is a workspace page and a knowledge doc and a scheduled task rolled into one.** That is a tool. Propose `tool-developer` under Bucket 7 rule 9, not a workspace extension. ## How to prompt One sentence. Name the page, the source of data, and the interaction shape. > "Want me to build a workspace page for X? Reads from Y, refresh on nav-load, no writes." Get an explicit yes before doing anything durable. On approval, either: - Invoke `pa-init workspace-extension ` for the file skeleton plus nav entry (add `--with-api` if the page needs a server route), then dispatch `tool-developer` for the real page content and any handler logic, OR - Skip the scaffold verb and dispatch `tool-developer` directly if the shape is unusual enough that the skeleton would just be deleted. The scaffold verb is a thirty-second cost saver; it does not replace the design conversation. ## Related - CLAUDE.md.template Bucket 7 rule 9 (proactive tool proposal): the parent rule; workspace pages count as a tool for that rule. - `@stravica-ai/engineering-pa-workspace/README.md`: the extension mechanism, page overlay, API-route registration, nav merge, team scoping. - `packages/core/knowledge/platform-tooling/workspace-server.md`: workspace server operations (start, stop, viewer.html).