chamba 0.7.0 → 0.8.0

package/templates/skills/chamba-statusline/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: chamba-statusline
-description: Explain where a session's status lives in chamba - the strip in the web interface, the snapshot behind it, and the context-usage helper. Use when the user mentions the status line, asks why the terminal has none, asks what the strip above the composer means, or wants a status line of their own.
+description: Explain where a session's status lives in chamba - the strip in the web interface, and the snapshot behind it. Use when the user mentions the status line, asks why the terminal has none, asks what the strip above the composer means, or wants a status line of their own.
+metadata:
+  audience: claude
 ---
 
 # chamba-statusline: Where a session's status is
@@ -25,31 +27,17 @@ The web interface shows the attached session's status in one line between the te
 
 The strip belongs to the session it is drawn for, and only a claude session has one - the snapshot is a Claude Code feature, so a codex or opencode tab has no strip at all.
 
-## Step 2 - The snapshot behind it, and the helper
+## Step 2 - The snapshot behind it
 
 The script at `{{statusline_path}}` is what makes any of this exist. Claude Code runs it on every prompt render and hands it the session's state on stdin; the script parses it, resolves the pid of the claude process it was run by, and writes a small JSON file. Fields: `session_id`, `claude_pid`, `claude_pid_start`, `updated_at`, `context_tokens`, `context_used_pct`, `context_window_size`, `model`, `effort`, `quota_left_pct`, `quota_resets_at`, `quota_week_left_pct`, `quota_week_resets_at`, `version`. The two `quota_*` pairs are the five-hour and seven-day rate-limit windows; both percentages are what is LEFT, inverted from the percentage used that Claude Code reports.
 
-Two things read those files:
-- The web interface, which matches a snapshot to a session by that pid and draws the strip from it.
-- The `context-usage` command, which is how an agent inspects its own context and quota from the terminal. Run it rather than reading the files by hand.
-
-If the user wants the numbers without the browser, `context-usage` is the answer. It prints one labelled line per thing the snapshot carried:
-
-```
-session: 78b4025b-... (this session, updated 3s ago)
-context: 70.8k tokens (7% of 1M window)
-quota:   84% remaining, resets in 21m
-weekly:  59% remaining, resets in 4d 6h
-model:   Fable 5 (effort high)
-```
-
-`quota` is the five-hour window and `weekly` the seven-day one; a window the account does not have prints no line at all, and neither does a field the snapshot is missing. The `(this session, ...)` marker means the snapshot was matched to the asking session by pid and is certainly its own; without it the newest file was used instead, and a `warning:` line says why that may mislead. The numbers are as of the moment the current prompt was submitted, so the turn in flight is not in them yet.
+The web interface reads those files: it matches a snapshot to a session by that pid and draws the strip from it. The numbers are as of the moment the current prompt was submitted, so the turn in flight is not in them yet.
 
 ## Step 3 - When the user wants a status line of their own
 
 The chamba script prints nothing on purpose: a status line is redrawn inside the conversation, so in a browser it scrolls away with the output and costs a row of the terminal every prompt. The strip is the same information somewhere it stays put.
 
-A user who works in the terminal and wants a visible line back can have one - by pointing Claude Code at their own script. Explain the trade first (a custom script replaces chamba's, and chamba's is what writes the snapshots the strip and `context-usage` read), then offer to write one that renders a line AND keeps the snapshot side effect: copy `{{statusline_path}}` and add rendering to it, rather than starting from nothing.
+A user who works in the terminal and wants a visible line back can have one - by pointing Claude Code at their own script. Explain the trade first (a custom script replaces chamba's, and chamba's is what writes the snapshots the strip reads), then offer to write one that renders a line AND keeps the snapshot side effect: copy `{{statusline_path}}` and add rendering to it, rather than starting from nothing.
 
 ### Permissions: you perform the edits
 
@@ -74,7 +62,7 @@ Never edit `{{statusline_path}}` directly - it is root-owned and read-only insid
    cp {{statusline_path}} ~/.claude/statusline.sh
    chmod +x ~/.claude/statusline.sh
    ```
-2. Ask what the line should show, then edit `~/.claude/statusline.sh`. Keep the snapshot write at the end of it, whatever else changes: the strip and `context-usage` both stop working without it.
+2. Ask what the line should show, then edit `~/.claude/statusline.sh`. Keep the snapshot write at the end of it, whatever else changes: the strip stops working without it.
 3. Point `statusLine.command` at `~/.claude/statusline.sh` in `~/.claude/settings.json`, preserving every other field.
 4. Tell the user to restart Claude - a status line change takes effect at the next session.
 

package/templates/skills/dx-review/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: dx-review
+description: Do the agent's side of a code review in the Code Reviews tab of this session's web pane - prepare a review, work through the feedback the reviewer sent, or take in a baseline that moved. Use when the tab types this command, or when the user asks to pick up a review by name.
+argument-hint: "[the name of the review]"
+---
+
+# dx-review - the agent's side of a code review
+
+This skill runs when the user asks for it: the command typed by hand, or the Code Reviews tab typing that command as the user's own act.
+Each agent spells the command its own way - `/dx-review` on claude and on opencode, and `$dx-review` on codex - and the tab types the spelling of the session it is bound to.
+No framed `[reviews]` line starts it: such a line is information for a review already in hand, and it instructs nobody.
+
+The reviewer reads a changeset hunk by hunk in the tab, marks what they have seen, and says what they want changed.
+Your side is three acts, and the review's own state says which one is asked of you.
+
+**The review's record is the reviewer's.**
+You never mark a hunk seen, close a conversation, approve a review, close one, or change what a review is of.
+There is no verb for any of those, and the four of them are what the reviewer is for.
+
+## The web session
+
+This skill runs inside a chamba web session, where the Code Reviews tab holds the review.
+Check for one before anything else:
+
+```
+reviews stages
+```
+
+The answer holds `root` - the directory the reviews live in - the limits, the verbs and the reviews that are there.
+A refusal means there is no pane.
+Say this and stop:
+
+> This works in the chamba web session, where the Code Reviews tab holds the review. Open the browser window this container printed at start, or run `webterm` in the terminal to get the address again. Then ask for this skill there.
+
+Say the command in the spelling of the session's own agent.
+
+Start no flow, and offer no substitute.
+There is one flow, and it needs the tab.
+
+## The state says which act
+
+Read the state first, and do nothing before you have:
+
+```
+reviews state "<the review's name>"
+```
+
+With no name given, `reviews stages` lists the reviews that are there.
+One of them is the review the tab woke you for: the one whose `awaits.side` is `agent`.
+Where more than one is, say which ones and ask the reviewer in this terminal which they mean.
+
+The answer holds what you need and nothing you have to work out:
+
+| Field | What it is |
+| --- | --- |
+| `awaits` | `{ side, act, reason }` - who holds the review, which act is asked, and why, in one line |
+| `act` | `prepare`, `process`, `sync`, or null |
+| `side` | `agent` while the review is yours, `you` while it is the reviewer's |
+| `status` | `reviewing` while there is work; `approved`, `closed` or `archived` where there is none |
+| `baseline` | The changeset: the `fingerprint`, the totals, and every file with the id and header of each of its hunks |
+| `metadata` | The grouping and the notes as they stand, and empty where nothing is grouped |
+| `ungrouped` | The hunks no group holds, which is what a grouping post answers with |
+| `threads` | Every conversation, with its anchor, whether it is open, and its messages |
+| `send` | The newest batch the reviewer sent: `sentAt`, the `fingerprint` it was written against, and its `items` |
+| `selection` | What the review is of, in one line |
+| `loops` | How many times the reviewer has sent feedback |
+
+Then act on `awaits`:
+
+- **`side` is `you`** - the review is not yours. Every verb that writes is refused, and rightly. Say the review is with the reviewer and stop.
+- **`status` is not `reviewing`** - the review is finished. Say so and stop.
+- **`act` is one of the three** - do that act. `references/acts.md` holds each one in detail; read the one you are doing.
+- **`act` is null and `side` is `agent`** - there is nothing waiting. Say so in this terminal and post nothing at all, `activity` and `done` included.
+
+The last two cases are real cases, not faults.
+The tab types this command for every act that hands a review over, and "Ask the agent to continue" types it again on a review that may be in hand already, so the command arriving is not by itself work to do.
+A review that came back to the reviewer a moment ago answers `side: you`, and there is nothing for you in it.
+
+### The three acts, in one line each
+
+- **`prepare`** - the review has a baseline and no grouping. Group every hunk into a few pieces of work, give each group a narrative, and write the notes: `info` where an explanation helps the reviewer, `attention` where a passage needs a human eye, `issue` where you are certain something is wrong.
+- **`process`** - the reviewer sent a batch. Do what each item asks, and reply in the conversation each item opened.
+- **`sync`** - the baseline moved, because the reviewer synced the review, stopped you, or followed a merge. Group what is new, and revise what the new code made wrong.
+
+## What you post
+
+Five verbs, and they are the whole of what you may do to a review:
+
+```
+echo '<json>' | reviews metadata "<review>"    the grouping and the notes for this baseline
+echo '<json>' | reviews reply    "<review>"    one reply in one conversation: { thread, text }
+echo '<json>' | reviews activity "<review>"    what you are doing right now: { said, groups? }
+echo '<json>' | reviews log      "<review>"    one dated line for the activity log: { said }
+reviews done "<review>"                        your act is finished
+```
+
+A payload is JSON on stdin, and the answer is JSON on stdout.
+`references/acts.md` holds the shape of each payload.
+
+**Post `activity` as you go.**
+It is one short sentence in the present tense - "Grouping the parser changes", "Working on the second item" - and the tab shows it with the time you posted it.
+A review that has said nothing for ten minutes is drawn as stale, so a long act posts as it moves rather than once at the end.
+
+**Post `done` last, and only when the act is finished.**
+It hands the review back to the reviewer, and the tool recomputes the baseline as it does.
+So a `metadata` or a `reply` after `done` is refused: the review is no longer yours.
+
+**Change no code that the act did not ask for.**
+`done` recomputes the baseline from the tree as it stands, so any edit of yours becomes part of what the reviewer reads, and the marks they made are carried onto it.
+`prepare` and `sync` are reading acts: group it, note it, reply, and leave the code alone.
+`process` is the one act that writes code, and it writes what the reviewer asked for and no more.
+
+**A grouping is posted against the baseline you read.**
+The post carries that baseline's `fingerprint`, and a post against a fingerprint that has moved on is refused with the reason.
+That is not an error to work around: the reviewer changed what the review is of while you worked, the review awaits you again, and the answer is to read the state and work from the baseline that is there now.
+
+## When you are not sure
+
+Ask the reviewer, in this terminal, and wait for the answer.
+A piece of feedback that could mean two things is worth one question; a guess costs the reviewer a whole loop of the review.
+
+The one thing never to do with an unclear item is to reply in its conversation as though it were settled.
+A reply is your answer to what was asked, and the tab shows it as one.

package/templates/skills/dx-review/references/acts.md

@@ -0,0 +1,162 @@
+# The three acts, in detail
+
+Read the act you are doing.
+`SKILL.md` says how you learn which one that is: `reviews state "<review>"`, and then `awaits.act`.
+
+Everything here is posted with the verbs of `SKILL.md`, and nothing else writes to a review.
+
+## prepare - the review has a baseline and no grouping
+
+The reviewer has filed a review and is waiting to read it.
+Until you post a grouping the screen shows every hunk under "Not grouped yet", which is a wall of diff with no story in it.
+So this act is the one the reviewer waits on longest, and it is the one that decides how the review reads.
+
+**1. Read the change before you group it.**
+The state's `baseline` holds every file and, for each one, the id and header of each of its hunks.
+Read the code itself as well - the files of the workspace are there, and the review is of the tree you are in.
+A grouping written from headers alone groups by file, which the tab could have done without you.
+
+**2. Group by intent, not by file.**
+A group is a piece of work somebody did: "the discount rules", "the new error path", "the rename that follows from it".
+Three to seven groups reads well for most changesets.
+One group of forty hunks says nothing, and twenty groups of two are the file list again.
+
+- A hunk may sit in several groups where it belongs to both.
+- A hunk in no group lands under "Ungrouped", which is the tool's own group. It is for the case where you missed one, and a review that shows it is a review you left half grouped.
+- `ungrouped` in the post's answer is that list. Read it, and post again with the hunks it names in the groups they belong to.
+
+**3. Give each group a narrative and its facts.**
+The narrative is a short paragraph in plain language: what this piece of work does, and why the change is what it is.
+The reviewer reads it before the hunks, so it says the thing the diff cannot - the intent.
+The facts are a few short lines of what is true and checkable: "adds one table column", "no call site outside the cart", "the old path stays for one release".
+Facts are facts. Anything that needs "I think" is not one.
+
+**4. Write the notes.**
+You read every line of this change, and the reviewer has not.
+The notes are what you learned while you read, beside the code, so that the human review is quick and misses nothing.
+A note is plain text of one kind, on one hunk or on a line range inside it.
+
+- `info` - an explanation that helps the reviewer understand the code: what a passage does, why the change is the way it is, what it mirrors elsewhere. "This mirrors the rule in `pricing.ts`." Write one wherever an explanation would save the reviewer a search or a guess.
+- `attention` - anything that deserves the reviewer's eyes, whether or not you found a fault in it: a hard passage, a change of behaviour, a decision with a trade-off, a place you believe is right and a human should confirm. "This drops the guard the caller used to hold." Attention is relative to this changeset: it marks the parts of this change that most need a human.
+- `issue` - something you are certain is wrong. The text says what is wrong in one or two sentences and, where you see it, how to fix it. "The loop never steps `i`, so it never ends. Step it at the end of the body." Write an issue only when you are sure; where you are not, write `attention` and say what you suspect.
+
+The screen counts the open `issue` and `attention` notes on each group and in the status bar, so the reviewer sees where the eyes are needed before they read.
+The reviewer can dismiss a note, ask you to fix an issue, or open a conversation on it.
+One note per thing you have to say, and the kind that fits it.
+A note on every hunk is a rail nobody reads, but a hunk that needs an explanation and has none is a question the reviewer has to ask you.
+
+**Do not fix anything in this act.**
+You found the issue, and the reviewer decides what to do with it: the fix is an item in the batch they send, and `process` is where you do it.
+
+**5. Post it.**
+
+```
+echo '{
+  "fingerprint": "sha256:...",
+  "groups": [
+    { "id": "discount-rules", "name": "Discount rules",
+      "narrative": "The rules move out of the cart and into one place ...",
+      "facts": ["adds one table column", "no call site outside the cart"],
+      "hunks": ["src/cart/discount.ts#9f3a...#1", "src/cart/discount.ts#9f3a...#2"] }
+  ],
+  "notes": [
+    { "hunk": "src/cart/discount.ts#9f3a...#1", "kind": "attention", "lines": [44, 46],
+      "text": "This drops the guard the caller used to hold." },
+    { "hunk": "src/cart/discount.ts#9f3a...#2", "kind": "issue", "lines": [61],
+      "text": "The loop never steps `i`, so it never ends. Step it at the end of the body." }
+  ]
+}' | reviews metadata "<review>"
+```
+
+`fingerprint` is the baseline's own, from the state you read.
+`id` is yours to choose and is the name the tool refers to the group by; `name` is what the reviewer reads.
+`kind` is `info`, `attention` or `issue`.
+`lines` are new-side line numbers inside the hunk, and a note without them is about the whole hunk.
+The screen draws one bar in the gutter from the smallest number to the largest, so two numbers name a range.
+
+**A post replaces the whole grouping.**
+That is what makes a group appear as it becomes ready: post the groups you have, and post them all again with the next one added.
+The screen then shows three groups, then four.
+A post with no group empties the grouping, which is what it says.
+
+**6. Say what you are doing, and finish.**
+Post `activity` as you work through it - "Grouping the parser changes, 3 of 5 ready" - and `done` when the grouping is complete and every note is in.
+
+**Say how many groups there will be, in `groups`.**
+
+```
+echo '{ "said": "Grouping the parser changes, 3 of 5 ready", "groups": 5 }' | reviews activity "<review>"
+```
+
+You are the only one who knows it: the tool holds the groups you posted, and the tab draws one card waiting for each group you promised and has not arrived, so the reviewer sees how much is still coming.
+Post it once you know the number, and post the sentence alone after that - the count stands until you post another, and it is cleared when the review goes back to the reviewer.
+
+## process - the reviewer sent a batch
+
+`send` in the state is the newest batch: when it was sent, the baseline it was written against, and its `items`.
+Each item is one thing the reviewer asked, and each one has already opened or joined a conversation on the hunk or the group it is about.
+
+An item carries:
+
+- `hunk` - the hunk it is about, or null for a comment on a group.
+- `group` - the group it is about, and null for everything else.
+- `act` - what the reviewer asked for: `undo` (undo the change), `explain` (explain it in a comment), `comment`, `fix` (fix what a note of yours says), or `group-comment`.
+- `lines` - the new-side lines the item is about, or null for the whole hunk or a group.
+- `text` - what they said, and it may be empty for an `undo` that speaks for itself.
+
+**Do the work first, and reply about what you did.**
+The order matters: a reply is a statement about the code, and a reply written before the change is a promise.
+
+- `undo` - put that hunk's change back as it was, unless doing so breaks something the reviewer cannot see. Where it does, do not undo it quietly: say what breaks, in the conversation, and leave the code as it is.
+- `explain` - the reviewer wants the reasoning, not a change. Answer in the conversation and change nothing.
+- `fix` - the reviewer read an `issue` note of yours and asks for the fix. The text is the note, with anything they added, and `lines` says where. Fix it, and reply with what you did.
+- `comment` and `group-comment` - read what they asked for and do it. It may be a change, a question, or both.
+
+**Reply in the conversation each item is on.**
+
+```
+echo '{ "thread": "<the thread id from the state>", "text": "Undone. The old guard is back, and ..." }' | reviews reply "<review>"
+```
+
+The `threads` in the state hold the id, the anchor and every message, so the thread of an item is the one whose anchor is that item's hunk or group.
+One reply per item, and each one lands live on the reviewer's screen under the hunk they were looking at.
+
+You cannot close a conversation, and you should not try to write a reply that reads like a closing.
+The reviewer closes a conversation when they are satisfied, and that is the whole point of the control.
+
+**Where an item is unclear, ask in the terminal.**
+Then do the item, and reply once you know what it asked.
+Do not reply with a question: a reply is your answer, and the tab draws it as one.
+
+**Finish with `done`.**
+It hands the review back and the tool recomputes the baseline, so the reviewer sees your commits as part of the review and every hunk they had read that you did not touch is still read.
+
+## sync - the baseline moved
+
+The reviewer synced the review, stopped you mid-act, or followed a merge.
+Either way the baseline is a new one, and the state's `metadata` is what you posted for the baseline before it.
+
+**What is already true, and what you do not have to do again.**
+The tool carried every mark, conversation and pending item onto the hunks that did not change, and it kept the grouping of every hunk that is still there.
+A hunk the reviewer had read whose content changed comes back unread with a "changed since you saw it" marker, which is the tool's, not a note of yours.
+
+So this act is the difference, and not the review again:
+
+1. **Group what is new.** `ungrouped` names the hunks no group holds. Most of them are new hunks, and each one belongs in a group that exists or in one more group.
+2. **Revise what the new code made wrong.** A narrative that describes code that is no longer there is worse than none, because the reviewer reads it as current. Read your own narratives against the new baseline and rewrite the ones that moved.
+3. **Read your notes again.** The tool dropped the notes of every hunk whose content changed, and kept the rest. Write again only the notes that are still true of the new code, and write notes for what is new. An issue you fixed gets no note: the rail shows the code as it is, not what it was.
+4. **Answer what is open.** A conversation the reviewer is waiting on is one that is open and whose last message is theirs. Answer it if the new code answers it.
+
+Post the whole grouping again, with the new baseline's `fingerprint`, and `done` when it is in.
+
+## The no-act case
+
+`awaits.act` is null, so none of the three applies.
+It happens two ways, and both are ordinary.
+
+- **`side` is `you`.** The review is with the reviewer. It came back to them when the last act posted `done`, or they stopped you and are reading it now. The command arrived because they asked again, or because it was typed by hand.
+- **`side` is `agent` and `act` is null.** The review is yours and names no act, which is a review that has nothing pending in it.
+
+Say so in the terminal, in one line, and post nothing.
+Not `activity`, and not `done`: `done` recomputes the baseline and hands back a review that was never taken, and the reviewer reads that as work that happened.
+Where the review is the reviewer's, every verb that writes is refused in any case, and the refusal is the right answer rather than something to work around.