@workser/cli 0.3.0 → 0.6.0

package/skills/workser/reference/sdlc-entities.md

@@ -1,16 +1,16 @@
 ---
 topic: sdlc-entities
-title: Board cards, decisions, requirements, and docs
+title: Board cards, decisions and requirements
 summary: Read what this project already tracks and decided, keep the Board honest as you work, and record what a future maintainer will need.
-commands: [board, decision, requirement, doc]
+commands: [board, decision, requirement]
 ---
 
-# Board cards, decisions, requirements, and docs
+# Board cards, decisions and requirements
 
 These are the project's memory across sessions. They write to the **same tables**
-the Orbit desktop's Board, Project Memory, and Docs panels use, so anything here
-appears there too — and (when this CLI runs inside an Orbit-spawned agent run)
-as an inline card in the conversation you're working in.
+the Orbit desktop's Board and Project Memory panels use, so anything here appears
+there too — and, inside an Orbit-spawned run, as an inline card in the
+conversation. Documents have their own guide: `workser help docs`.
 
 ```
 workser board list [--status <value>] [--label <value>] [--limit <n>]
@@ -33,11 +33,6 @@ workser requirement show <id>
 workser requirement create <title> --body <text> [--status <text>]
 workser requirement update <id> [--title <text>] [--body <text>] [--status <text>]
 
-workser doc list [--work-item <id>]
-workser doc show <id> [--markdown]
-workser doc create <title> [--work-item <id>] [--markdown <text>]
-                            [--content-json <json>]
-workser doc update <id> [--title <text>] [--markdown <text>]
 ```
 
 ## Read first — this is the part that matters
@@ -66,7 +61,6 @@ workser board create "Phase 1 — schema + migration" \
   --description "Add orders/line_items tables and the migration." \
   --status in-progress --json
 workser board create "Phase 2 — checkout API" --description "…" --json
-workser board create "Phase 3 — cart UI"      --description "…" --json
 
 # the plan itself, ONE doc, deliberately NOT linked to a card
 workser doc create "Checkout — implementation plan" --markdown "$(cat plan.md)" --json
@@ -76,8 +70,8 @@ workser decision create "Carts live server-side" --context "…" --decision "…
 ```
 
 **Don't pass `--work-item` for a multi-phase plan.** A linked document renders on
-its card and is *hidden* from the Docs panel; a plan spanning three phases belongs
-to the project, not to phase 1.
+its card and is *hidden* from the Docs panel; a plan spanning three phases
+belongs to the project, not to phase 1.
 
 The bar: if the user closed this conversation now, the Board should still show
 what's left and the doc should still explain the plan to whoever continues it.
@@ -103,22 +97,19 @@ workser board create "Fix the login bug" --status in-progress --priority high \
 ```
 
 `board update` replaces the labels you pass rather than merging them, and
-touches only the fields you name. There is no `board delete` — `done` is the
-terminal state for finished work, and removing a card the user filed is theirs
-to do in Orbit.
+touches only the fields you name. There is no `board delete`: `done` is the
+terminal state, and removing a card the user filed is theirs to do in Orbit.
 
 ## Decisions are append-only
 
 `decision create` is for something with real tradeoffs worth a paper trail:
-`--context` is why it came up, `--decision` is what was decided,
-`--consequences` is the follow-on effects. There is deliberately **no
-`decision update`** — a decision record states what was decided at a point in
-time. When it stops being right, record a new decision that supersedes it and
-say so in its `--context`. Editing the history is how a decision log stops
-being worth reading.
+`--context` is why it came up, `--decision` what was decided, `--consequences`
+the follow-on effects. There is deliberately **no `decision update`** — a record
+states what was decided at a point in time. When it stops being right, record a
+new decision that supersedes it and say so in its `--context`. Editing the
+history is how a decision log stops being worth reading.
 
-Requirements are different: they legitimately move along, so they do have
-`update`.
+Requirements legitimately move along, so they do have `update`.
 
 ```
 workser requirement create "Support SSO" --body "Enterprise customers need SAML." \
@@ -129,22 +120,8 @@ workser requirement update <id> --status done
 ## Docs
 
 `--markdown` is the normal way to write one. The body is stored both as the
-rich-text content the Docs panel renders and as a git-tracked markdown mirror
-at `.workser/docs/<id>.md` — `workser doc show <id> --markdown` reports that
-path so you can read the file with your normal tools.
+rich text the Docs panel renders and as a git-tracked mirror at
+`.workser/docs/<id>.md`; `workser doc show <id> --markdown` reports that path so
+you can read the file with your normal tools.
 
-Revise the page that exists rather than creating a second copy of it:
-
-```
-workser doc list --json                       # is there already a page for this?
-workser doc update <id> --markdown "$(cat updated.md)"
-```
-
-`--work-item <id>` links a document to a Board card (a card has at most one).
-
-## When to record, and when not to
-
-Record what a future maintainer would need: follow-up work you found but didn't
-do, a choice between real alternatives, a behaviour worth writing down. Don't
-narrate every small step — and never treat filing a card as a substitute for the
-work. A card saying "fix the bug" is not fixing the bug.
+Revise trd saying "fix the bug" is not fixing the bug.

package/skills/workser/reference/tasks.md

@@ -22,6 +22,7 @@ workser task subtask add <title> [--role <value>] [--kind <value>]
 workser task subtask list [taskId]
 workser task subtask update <id> [--title|--note|--role|--kind|--scope]
 workser task subtask remove <id>
+workser task subtask send-back <id> --note <text>   # redo it, and say why
 
 workser task can-start [id]             # may work begin? refuses until approved
 workser task approval request           # tell the owner the plan is ready
@@ -80,3 +81,23 @@ workser task done --summary "The report now shows cost per KOL, with six months
 ```
 
 Write the summary for someone who runs a business and does not read code.
+
+## Sending a step back
+
+A step that finished but is not good enough is **sent back**, not replaced:
+
+```
+workser task subtask send-back 3f2a… --note "The totals ignore refunds."
+```
+
+That puts it in the queue again as a **second attempt** on the same step. Two
+reasons it matters that this is not a new step:
+
+- The owner's screen can then say *"1 send-back, fixed — 2nd run passed"*. A
+  replacement step says only that two steps exist, which tells them nothing
+  about whether their team caught its own mistake.
+- `--note` is the reason, and it is recorded against the attempt being
+  rejected. Without it the history can say a step ran twice but not why.
+
+It refuses a step that is still working. Let it finish first — the run is
+still writing to it.

package/skills/workser/reference/usage.md

@@ -0,0 +1,48 @@
+---
+topic: usage
+title: Usage — what is being used, against the plan
+summary: How much database, file storage, projects and apps are in use, and how close that is to what the plan allows.
+commands: [usage]
+---
+
+# Usage — what is being used, against the plan
+
+```
+workser usage        # storage, projects, apps — and how close each is to the limit
+```
+
+Run it before you propose anything that adds to a count. "Create another
+project" is a plan you can only sensibly make if you know the plan allows two
+and two already exist.
+
+## Two scopes in one answer, on purpose
+
+* **Database and files are ORGANISATION-wide.** One pool across every project.
+  There is no per-project storage limit, and reporting one would invent it.
+* **Projects, and apps in this project, are counted where they apply.** These
+  are the limits people actually hit.
+
+## Two kinds of limit, which do not mean the same thing
+
+* **Hard cap** — projects, apps. Going over is **refused**. `workser usage`
+  exits non-zero when one is reached, so a step can gate on it.
+* **Soft allowance** — database, files. Going over is **billed as extra**,
+  never blocked. It does not fail the command, because a customer growing past
+  their allowance should not have their automation start breaking that day.
+
+## "not measured" is not zero
+
+A figure that could not be read prints as `not measured`, with the reason, and
+draws no bar. Do not report it as `0`, and do not tell the user they have room
+based on it — nobody looked.
+
+If a scan comes back with a figure missing, say which one and why. "Your
+database is using 2.5 GB of 10; the file total could not be read" is a useful
+sentence. "You are using 2.5 GB of 20" is not, and it is wrong.
+
+## What to do with it
+
+- Near a **soft** limit: tell the owner what the extra will cost them, and what
+  is taking the space. Do not delete anything to make a number look better.
+- At a **hard** cap: say which plan raises it. Do not attempt the create — it
+  will be refused, and a failed attempt reads to the owner as a broken product.