@paxnax/berliner 0.0.0-stage → 0.2.0

package/skill/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: berliner
+description: Use when you commit, open or update a pull request, or finish a task, and whenever the user asks you to report to Berliner. Reports the task, pull requests, test coverage and screenshots or videos with the berliner CLI.
+---
+
+# Reporting to Berliner
+
+Berliner records what an autonomous session cost and produced. You report with one command, `berliner report`.
+
+## When to report
+
+- Before your final message, whenever you committed, opened or updated a pull request, or finished a task.
+- Again whenever a PR changes (opened, merged, CI finishes) or you add evidence.
+- Right away when the user asks you to report to Berliner.
+
+Reporting again is safe. The new values replace the old ones, PR URLs are added to the list, and evidence already uploaded is skipped. It never double-counts.
+
+## Inside Claude Code, Codex or OpenCode
+
+Hooks installed by `berliner setup` already report the session's cost, model, repository and commits after every reply. Send only what you know and the hooks don't:
+
+| Flag | What to send |
+|---|---|
+| `--title` | A short line naming the task. |
+| `--task`, `--task-url` | The ticket ID and its URL, if there is one. |
+| `--pr` | Every pull request, one flag each. |
+| `--coverage` | Percent, from the test run's coverage summary. |
+| `--evidence` | Each screenshot or video. |
+
+Do not pass `--session-id`, `--cost` or `--model`: the CLI fills them in from the tool's own records, and an explicit value is ignored with a warning. `--repo` and `--plan` are not needed either: the plan comes from the user's `BERLINER_PLAN`, or from their subscriptions in Settings. A report without `--title` keeps the session's existing title. `berliner update` ignores a session ID here.
+
+## Outside those tools
+
+Without a hook, `report` needs these flags:
+
+| Flag | Source |
+|---|---|
+| `--session-id` | Your harness's session ID if it exposes one, otherwise generate a UUID at the start of the session and reuse it for every report. |
+| `--title` | One short line describing the work. |
+| `--repo` | `owner/name`, from `git remote get-url origin`. |
+| `--cost` | Estimated USD. Your harness's reported session cost if it shows one, otherwise estimate from token usage at the model's API prices. |
+| `--model` | The primary model ID you ran on. |
+| `--plan` | Your best guess at the plan you run on. Claude: `free`, `pro`, `max_x5`, `max_x20`, `team`, `enterprise`. OpenAI (Codex): `free`, `go`, `plus`, `pro`, `pro_more`, `pro_max`, `business`, `business_premium`. Billed per token: `api`. Always pass it: when the user has set `BERLINER_PLAN`, that value replaces yours. |
+
+Report again with the same `--session-id` whenever something changes.
+
+## Optional values
+
+- `--commits <n>` (outside the tools; the hooks count them): `git rev-list --count <base>..HEAD`
+- `--coverage <percent>`: from the test run's coverage summary.
+- `--pr <url>[,merge=<open|merged|closed>][,ci=<pending|running|passed|failed|none>]`: repeat per PR. URL from `gh pr view --json url`.
+- `--evidence <path>[::caption]`: repeat per screenshot or video.
+- `--task <id>`, `--task-url <url>`, `--project <name>`, `--started-at <ISO>`, `--ended-at <ISO>`.
+
+Quote any value that contains spaces.
+
+## Environment
+
+`berliner setup` stores the API token in a config file, so `BERLINER_TOKEN` is only needed to override it (a token from the Settings page at https://berliner.app). `BERLINER_URL` overrides the server address. `BERLINER_PLAN`, when the user sets it, replaces any `--plan`.
+
+If the `berliner` command is not found, ask the user to run `npx @paxnax/berliner@latest setup`. Do not try to install it yourself.
+
+## Timeouts
+
+The session is saved first, then evidence is uploaded. Allow at least 10 minutes for the command when attaching videos.
+
+## Reading the output
+
+- Success prints what was saved, then an evidence line such as `Evidence: 1 uploaded, 0 already uploaded, 0 skipped.`
+- A line starting `berliner:` on stderr is a warning: the report may be incomplete (server unreachable, a file skipped). The command still exits 0, so it never fails your work (`--strict` makes failures exit 1). Re-run the same command; it is safe to repeat.
+- `--json` prints the saved session as JSON, plus an `evidence` field with `uploaded`, `existing` and `skipped` results when `--evidence` was given.
+- To change a field later without resending everything, use `berliner update --commits 5` inside the tools, or `berliner update <session-id> --commits 5` outside them.
+
+## Examples
+
+Inside Claude Code, Codex or OpenCode:
+
+```sh
+berliner report \
+  --title "Fix recurring event off-by-one" \
+  --task TEC-5521 \
+  --task-url https://linear.app/octo/issue/TEC-5521 \
+  --coverage 87.5 \
+  --pr "https://github.com/octo/app/pull/42,ci=running" \
+  --evidence "./shots/after.png::Calendar after the fix"
+```
+
+Anywhere else:
+
+```sh
+berliner report \
+  --session-id 3f1c2a9e-7b64-4d0a-9a51-2c8f0e6d1b77 \
+  --title "Fix recurring event off-by-one" \
+  --repo octo/app \
+  --cost 4.20 \
+  --model claude-opus-5-5 \
+  --plan max_x20 \
+  --task TEC-5521 \
+  --commits 3 \
+  --coverage 87.5 \
+  --pr "https://github.com/octo/app/pull/42,ci=running" \
+  --evidence "./shots/after.png::Calendar after the fix"
+```