@workser/cli 0.2.6 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workser/cli",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "Workser CLI — give your local AI agent native DevOps & infrastructure on Workser. The agent runs `workser …` to provision, deploy, and manage real apps.",
   "license": "MIT",
   "type": "module",

package/skills/workser/SKILL.md

@@ -5,19 +5,16 @@ description: Provision, deploy, and operate the current Workser app. Use when th
 
 # Workser — ship & run the current app from the terminal
 
-You have the `workser` CLI. It lets you act as the user's DevOps engineer for the
-**one project** Workser Orbit has linked to this directory: provision and browse its
-Neon Postgres database, deploy it, manage its env vars and bucket, provision auth,
-and read its logs — **on the user's own account**, through the Workser Orbit app
-(which handles auth and shows the user what you're doing).
-
-For writing code, keep using your normal tools. Use `workser` for the last mile.
+You have the `workser` CLI. Use it to operate the **one project** Workser Orbit has
+linked to this directory — infrastructure, config, shipping — **on the user's own
+account**, through the Orbit app, which handles auth and shows them what you're
+doing. For writing code, keep using your normal tools.
 
 ## Read one guide, not all of them
 
-This page is the index. The detail lives in the CLI itself — `workser help <topic>`
-prints one focused guide, about a screen long. Find your row, run that **one**
-command. Don't print them all; you are paying for every line you load.
+This page is the index. `workser help <topic>` prints one focused guide, about a
+screen long. Find your row, run that **one** command — you pay for every line you
+load.
 
 | You need to… | Commands | Run |
 | --- | --- | --- |
@@ -25,6 +22,7 @@ command. Don't print them all; you are paying for every line you load.
 | Follow the project's brand — colours, fonts, logo | `design …` | `workser help brand` |
 | Provision or query Postgres; list end users | `db …`, `auth …` | `workser help database` |
 | Deploy, set env vars, read logs, check a domain | `deploy`, `env …`, `logs`, `versions`, `domain`, `open` | `workser help deploy` |
+| Save work before a risky change, undo it, sync this folder | `checkpoint`, `restore`, `sync` | `workser help version-control` |
 | Put files in the project's bucket | `storage …` | `workser help storage` |
 | Read or write products, orders, customers, deals | `business …` | `workser help business` |
 | Use the project's own Neon buckets or functions | `neon …` | `workser help neon` |
@@ -35,9 +33,8 @@ command. Don't print them all; you are paying for every line you load.
 | Record finished output, or ask the user a question | `artifact …`, `ask` | `workser help deliverables` |
 | Control this machine — files, shell, screen, browser | `tool …` | `workser help computer-use` |
 
-`workser help` with no topic lists them. **The CLI is the source of truth** — it
-ships these guides itself, so they match the version you are running, and
-`workser <command> --help` is generated from the implementation.
+`workser help` lists them all; `workser <command> --help` gives exact flags. Both
+come from the CLI itself, so they match the version you are running.
 
 ## Orientation (no guide needed)
 
@@ -123,6 +120,8 @@ workser board close <id> --json             # 9. the Board now matches reality
   - `no_project` → no project is linked here; the user links it in Orbit.
   - `owner_only` → an owner action; tell the user to do it in Orbit, then continue.
   - `awaiting_approval` → user must approve in Orbit; then retry.
+  - `needs_local_app` → this machine has no Workser app, so folder commands
+    can't run. Say so; don't reach for `git` instead.
 
 Keep the user informed in plain language ("Provisioned a database and deployed —
 it's live at <url>"), not raw JSON.

package/skills/workser/reference/tasks.md

@@ -0,0 +1,82 @@
+---
+topic: tasks
+title: Project tasks & subtasks
+summary: The ticket you are working inside: read it, break it into steps, and ask before starting.
+commands: [task]
+---
+
+# Project tasks & subtasks
+
+A **project task** is a ticket the owner filed. You are usually running inside
+one — Orbit sets `WORKSER_PROJECT_TASK_ID` on your process, so every command
+below defaults to it and you rarely pass an id at all.
+
+```
+workser task list [--status <value>] [--label <value>] [--limit <n>]
+workser task show [id]                  # the task you are in, with its steps
+
+workser task subtask add <title> [--role <value>] [--kind <value>]
+                                 [--note <text>] [--app <id...>]
+                                 [--infra <ref...>] [--scope <path...>]
+                                 [--depends-on <key...>]
+workser task subtask list [taskId]
+workser task subtask update <id> [--title|--note|--role|--kind|--scope]
+workser task subtask remove <id>
+
+workser task can-start [id]             # may work begin? refuses until approved
+workser task approval request           # tell the owner the plan is ready
+workser task move <id> <status>
+workser task done [id] --summary <text>
+```
+
+## This is not `workser board`
+
+`board` is the Orbit Board — a human's list of work items. `task` is the AI Tech
+Team's own table. Filing your plan on the Board puts it somewhere the owner's
+task page never reads: they see "created work item" and an empty plan. Use
+`task subtask add`.
+
+## Planning a task
+
+Read the project first, then propose. One `subtask add` per step:
+
+```
+workser task subtask add "Build the upload endpoint" \
+  --role api --kind service \
+  --note "Accept a file, work out its type, hand it to the right analyzer." \
+  --scope src/app/api/analyze/route.ts
+
+workser task subtask add "Check every supported file type end to end" \
+  --role qa --depends-on RIZZ-15
+```
+
+`--role` is one of: pm, architect, web, api, automation, qa.
+`--kind` is what the step produces: data_reports, web, mobile, service,
+automation, docs. It is not the same fact as the role — the same engineer
+writing a screen, the docs for it and the service behind it is three kinds of
+work.
+
+`--scope` is what that step OWNS. Two steps naming the same file cannot run at
+the same time, so keeping scopes apart is what lets the team work in parallel.
+`--depends-on` takes the keys you read off `task show`.
+
+Between three and six steps. If it needs more, say the task is too big instead.
+The step that CHECKS work must not be the same role as the one that built it.
+
+## Nothing runs until the owner approves
+
+```
+workser task can-start
+```
+
+This exits non-zero, with the reason, until they have approved the plan — that
+refusal is the product working, not an error to route around. Ask with
+`workser task approval request`; only a person can answer.
+
+## Finishing a step
+
+```
+workser task done --summary "The report now shows cost per KOL, with six months of history."
+```
+
+Write the summary for someone who runs a business and does not read code.

package/skills/workser/reference/version-control.md

@@ -0,0 +1,66 @@
+---
+topic: version-control
+title: Saving, undoing & syncing your work
+summary: Checkpoint before risky edits, restore when they go wrong, sync with Workser.
+commands: [checkpoint, restore, sync]
+---
+
+# Saving, undoing & syncing your work
+
+```
+workser checkpoint ["what you're about to try"]  # save the folder as it stands now
+workser restore                                  # go back to the newest checkpoint
+workser restore --list                           # see the checkpoints you can go back to
+workser restore <ref>                            # go back to a specific one
+workser sync [--branch dev] [--app <id>]         # reconcile this folder with Workser
+```
+
+## Why these exist instead of git
+
+This folder is a git repository, but **the history is Workser's**. There is no
+remote: code moves to and from Workser over its API as git bundles, using the
+same session everything else here uses. No credential is read, and the user's
+own git keys and identity are never touched.
+
+That is what makes any of this work on a computer with no access to the
+Workser-managed repository — which is every computer. Nobody has repo access;
+the API does.
+
+So the ordinary git verbs are wrong here, and these three replace them:
+
+| Instead of | Run |
+|---|---|
+| `git stash` | `workser checkpoint` |
+| `git commit` | `workser checkpoint` |
+| `git reset --hard` / `git checkout .` | `workser restore` |
+| `git pull` / `git push` | `workser sync` |
+
+Reading is always fine: `git log`, `git diff`, `git show`, `git status`.
+
+## Notes that matter
+
+- **Checkpoint before anything you might want to take back** — a refactor across
+  many files, a dependency upgrade, deleting something large. It costs a second.
+- **`git stash` is the one that actually loses work.** Workser publishes what is
+  on disk, so a deploy while your changes are stashed ships the version *without
+  them* — and if the run is stopped between `stash` and `stash pop`, the user
+  opens their folder and their work is gone. `workser checkpoint` has neither
+  failure mode.
+- **Restoring never discards anything.** The current state is saved first, then
+  the older state is restored on top. If you restore the wrong thing, restore
+  again. Say this to the user — it is the reason they can afford to say yes.
+- **These are the same checkpoints as the app's Undo button.** One history, not
+  two: a checkpoint you take here appears in Workser, and vice versa.
+- **`sync` pulls before it pushes.** If it reports `diverged`, both sides changed
+  and it stops rather than picking a winner — tell the user to resolve it in
+  Workser instead of forcing it.
+- **These three need the Workser app running on this computer**, because they
+  work with files. If you get `needs_local_app`, you are on a machine that only
+  has the CLI and a token — say so rather than looking for a workaround. Every
+  read-only command (`projects`, `env`, `db`, `logs`, `status`) still works.
+
+## Shipping is separate
+
+`workser sync` reconciles the folder. `workser deploy` puts it in front of
+users. Syncing does not deploy, and deploying does not require you to sync
+first — deploy publishes what is on disk. See `reference/deploy.md`.