@workscribe/cli 1.15.5 → 2.0.0

package/package.json

@@ -1,7 +1,29 @@
 {
   "name": "@workscribe/cli",
-  "version": "1.15.5",
+  "version": "2.0.0",
   "description": "Passive developer work journal — automatic terminal activity summaries",
+  "homepage": "https://workscribe.co",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/workscribe/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/workscribe/cli/issues"
+  },
+  "keywords": [
+    "cli",
+    "developer-tools",
+    "terminal",
+    "journal",
+    "work-journal",
+    "standup",
+    "productivity",
+    "ai",
+    "summary",
+    "git",
+    "time-tracking",
+    "shell"
+  ],
   "type": "commonjs",
   "bin": {
     "workscribe": "dist/index.js"
@@ -27,14 +49,8 @@
   },
   "files": [
     "dist",
-    "shell"
-  ],
-  "keywords": [
-    "developer-tools",
-    "journal",
-    "terminal",
-    "productivity",
-    "standup"
+    "shell",
+    "skills"
   ],
   "author": "Mark Edomwande",
   "license": "MIT",

package/skills/workscribe/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: workscribe
+description: Summarize the developer's recent work from Workscribe's captured terminal, IDE and AI-session activity, then save the summary back to Workscribe. Use when the user asks what they did today, this week or on a given day, wants a standup, status update or work log, or asks to summarize their sessions or commits. Requires the `workscribe` CLI.
+---
+
+# Workscribe work summaries
+
+Workscribe records the developer's commands, IDE saves, AI-tool sessions and commits on their machine. This skill reads that record, writes a short outcome-focused summary per work session, and saves it back — after which `workscribe summary`, `workscribe context` and the VS Code status bar show your summary instead of Workscribe's built-in one.
+
+## Rules that keep the record clean
+
+Every shell command you run is itself recorded by Workscribe. To avoid logging your own work as the developer's:
+
+- **Start every command with `workscribe`.** No `cd … &&`, no `npx`, no piping other commands into it.
+- **Never run `git`** (or `cat`, `grep`, `ls`, …) to dig for detail. Commits are already in the JSON. If a commit subject is too vague, read the relevant files under `repoPath` with your own file-reading tool instead of the shell.
+
+## 1. Get the sessions
+
+```bash
+workscribe sessions --json
+```
+
+Add `--date YYYY-MM-DD` for another day. For "this week", run it once per day (Monday to today) and save each day's sessions — but note `workscribe summary --week` keeps using Workscribe's own digest; saved summaries are per day. The output is one line of JSON; see [references/json-contract.md](references/json-contract.md) for the fields you'll use. An empty `sessions` list means nothing was captured — tell the user and stop.
+
+## 2. Write one block per session
+
+Follow [references/summary-format.md](references/summary-format.md). In short:
+
+```
+## <project> (<branch>) — <duration>
+- <outcome>
+```
+
+- Up to **7 bullets**, most important first: what was built, fixed, shipped or decided.
+- Build bullets from `commits` (cite the short hash, e.g. `(a1b2c3d)`), test and build results (`exitCode` 0 vs non-zero; `null` means unknown, never "failed"), `notes` (always include them), and `hint`s on unclassified events.
+- Describe outcomes, not commands or tools. Never name the AI tool used. Don't invent anything the data doesn't show.
+- Skip a session with nothing notable rather than padding it.
+
+## 3. Save each block
+
+Save each session's block with its `key`, as **one command starting with `workscribe`**:
+
+```bash
+workscribe sessions summary set --key 'api|2026-10-25T09:00:00.000Z' <<'EOF'
+## api (feature/auth) — 1h 30m
+- Fixed the token refresh race in the auth middleware (a1b2c3d)
+- Added regression tests for expired sessions; suite now passing
+EOF
+```
+
+Use the quoted `<<'EOF'` form so nothing in the summary is expanded. Saving again for the same key replaces the earlier summary.
+
+If it reports that **no session matches the key**, new activity regrouped the day: run `workscribe sessions --json` again and retry with the fresh key. Any other error message says what to fix.
+
+## 4. Tell the user
+
+Show the summaries, then say they were saved to Workscribe: `workscribe summary` (including `--slack`), `workscribe context` and the VS Code status bar now use them for those sessions. `workscribe summary --fresh` shows Workscribe's own summary for that run without removing yours.
+
+## Privacy
+
+Running this skill sends the JSON — categories, commit subjects, notes, short redacted hints for unclassified commands, and each session's repo path and working directory; never full commands or IDE file paths — to the model provider behind this agent, along with any files you read under `repoPath`. If the developer needs summaries that never leave their machine, point them to `workscribe summary`, whose template engine runs entirely offline.

package/skills/workscribe/references/json-contract.md

@@ -0,0 +1,43 @@
+# `workscribe sessions --json` — fields this skill uses
+
+The full contract is documented at workscribe.co/docs/commands#json-output-contract. Within `schemaVersion: 1`, fields are only ever added — ignore any you don't recognise.
+
+```json
+{
+  "schemaVersion": 1,
+  "date": "2026-10-25",
+  "sessions": [
+    {
+      "key": "api|2026-10-25T09:00:00.000Z",
+      "project": "api",
+      "repoPath": "/Users/dev/api",
+      "branch": "feature/auth",
+      "startedAt": "2026-10-25T09:00:00.000Z",
+      "endedAt": "2026-10-25T10:30:00.000Z",
+      "durationMinutes": 90,
+      "notes": ["blocked on staging credentials"],
+      "commits": [
+        { "hash": "a1b2c3d", "subject": "fix: token refresh race", "source": "git" },
+        { "hash": null, "subject": "wip: amended away", "source": "captured" }
+      ],
+      "events": [
+        { "category": "testing", "exitCode": 1, "metadata": { "tool": "npm" } },
+        { "category": "testing", "exitCode": 0, "metadata": { "tool": "npm" } },
+        { "category": "other", "hint": "make deploy-staging", "metadata": {} }
+      ]
+    }
+  ]
+}
+```
+
+| Field | Use it for |
+|---|---|
+| `key` | The `--key` when saving this session's summary. Copy it exactly. |
+| `project`, `branch`, `durationMinutes` | The block heading. `project` is the repo name, a `~/path` for work outside git, or `null` (write `unknown`). |
+| `repoPath` | Where to read files if a commit needs context. `null` outside a git repo. |
+| `notes` | The developer's own notes — always include them. |
+| `commits` | The main source of outcomes. `source: "git"` has a short `hash` to cite; `"captured"` commits have `hash: null` (amended or rebased). |
+| `events[].category` | What kind of work: `testing`, `building`, `shipping`, `dependencies`, `releasing`, `ai_session`, `code_edit`, `other`, … |
+| `events[].exitCode` | `0` passed, non-zero failed, `null` unknown (commands run by AI tools). A failure followed by a pass means a fix. |
+| `events[].metadata` | Structured detail: `packages` for dependencies, `tool`, `message`, `remote`/`branch` for pushes. |
+| `events[].hint` | Only on `other` events: a short, redacted start of the command. Infer intent from it; don't quote it. |

package/skills/workscribe/references/summary-format.md

@@ -0,0 +1,36 @@
+# Summary format
+
+One block per session, in exactly the shape Workscribe uses everywhere else, so saved summaries look native in `workscribe summary`, `workscribe context` and the VS Code status bar.
+
+## Heading
+
+```
+## <project> (<branch>) — <duration>
+```
+
+- Leave out ` (<branch>)` when `branch` is `null`.
+- If `project` is `null` (no repo and no events), use `unknown`, as Workscribe does.
+- Duration from `durationMinutes`: under an hour as `45m`; otherwise `1h` or `1h 30m`.
+
+## Bullets
+
+Up to **7**, each starting with `- `, most important first:
+
+1. Notes from `notes`, as written — prefix with `Note: `
+2. What was built, fixed or changed, from `commits` — cite the short hash in parentheses when there is one
+3. Test and build outcomes: "Resolved failing tests (now passing)", "Build still failing" — only when `exitCode` shows it; `null` exit codes are unknown, not failures
+4. Dependencies added or removed, releases and deploys, pushes — when they matter
+
+Write outcomes in plain past tense ("Fixed…", "Added…", "Shipped…"). Fold routine steps (installing, pushing, re-running) into the outcome they served. Never list commands, file names or the AI tool used. If several commits are steps toward one change, describe the change once.
+
+## Example
+
+Input (trimmed): commits `a1b2c3d fix: token refresh race` and `e4f5a6b test: expired session regression`, five `testing` events failing then passing, `dependencies` with `packages: ["jose"]`, note "blocked on staging credentials".
+
+```
+## api (feature/auth) — 1h 30m
+- Note: blocked on staging credentials
+- Fixed the token refresh race in the auth middleware (a1b2c3d)
+- Added regression tests for expired sessions (e4f5a6b); suite now passing
+- Switched JWT handling to the jose library
+```