@rmrdeveloper/sideroom-pi 7.0.1 → 7.1.0

package/README.md

@@ -1,162 +1,182 @@
-# Sideroom Pi
+# Sideroom Pi — the side room your agent was missing
 
 [![npm version](https://img.shields.io/npm/v/@rmrdeveloper/sideroom-pi?label=npm&logo=npm)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
 [![npm monthly downloads](https://img.shields.io/npm/dm/@rmrdeveloper/sideroom-pi?label=downloads&logo=npm)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
 [![npm license](https://img.shields.io/npm/l/@rmrdeveloper/sideroom-pi?label=license)](https://www.npmjs.com/package/@rmrdeveloper/sideroom-pi)
 
-Sideroom Pi is a global [Pi package](https://pi.dev/docs/latest/packages). It
-registers two parent-agent tools: `sideroom_ask`, a TUI questionnaire for
-clarifying decisions, and `sideroom_todo`, a live work board shown above the
-editor. It also shows a session-scoped list of files successfully edited by Pi,
-and steers write/edit toward packaged coding guidelines. It writes no `.pi`
-configuration, task graph, or other Sideroom files into the repository you are
-working in.
+> Coding agents fail in predictable ways: they guess instead of asking, they
+> bury progress in chat scroll, they litter your repo with `TODO.md` files,
+> and every session writes code in a slightly different style.
+>
+> **Sideroom fixes all four — without touching your repository.**
+
+Sideroom Pi is a global [Pi package](https://pi.dev/docs/latest/packages)
+that gives the parent agent a *side room* next to your code: a place to ask
+sharp questions, show live progress, track what changed, and stay honest
+about code quality. The room lives in the Pi session, not in your repo. No
+`.pi` config, no task graph, no Sideroom files left behind.
+
+## Why Sideroom exists
+
+Every long agent session drifts toward the same failure modes:
+
+1. **Silent guessing.** The agent hits an ambiguous decision and picks
+   something instead of asking — because asking in plain chat is awkward
+   and easy to ignore.
+2. **Invisible work.** "What is it doing? Which step is it on? Did it skip
+   something?" Progress disappears into thousands of lines of transcript.
+3. **Repo pollution.** Workarounds appear as `todos.json`, scratch notes,
+   and half-abandoned plans committed next to real code.
+4. **Style drift.** Each session reinvents conventions: nesting depth, error
+   handling, naming, validation. Review becomes cleanup.
+
+Sideroom answers each one with a small, opinionated surface:
+
+| Failure | Sideroom answer |
+| --- | --- |
+| Silent guessing | `sideroom_ask` — questions with an opinion, one batch at a time |
+| Invisible work | `sideroom_todo` — a live board above the editor, always one step in focus |
+| Repo pollution | Session-branch state — the board and history die with the session, never with a commit |
+| Style drift | A one-line reminder + the on-demand `sideroom-guidelines` skill |
+| Vague plans | `sideroom-grill` — an interview that settles the words before the work |
+
+## What it feels like
+
+You ask the agent for something non-trivial. Instead of vanishing into a
+wall of tool calls, it:
+
+- **Asks like a senior would.** A clean TUI questionnaire appears — tabs for
+  several questions, a simple list for one. Every question carries a
+  recommendation, you can always answer *Out of scope* or write your own,
+  and everything is written in your language. Escape cancels the whole
+  batch. No guessing, no twenty follow-up clarifications in chat.
+- **Works in the open.** A compact board sits above the editor:
+  `pending → in_progress → completed`. Exactly one step is active at a
+  time; the agent completes the current step and starts the next one in the
+  same move, so skipped steps become structurally hard. The board survives
+  reload, tree navigation, and compaction.
+- **Shows its traces.** Below the board, the last edited files appear as
+  clickable `file://` links. `F8` opens the full session history; `R` clears
+  it. Only successful Pi `write`/`edit` calls are tracked — no guesses from
+  shell output, Git, or subagents.
+- **Writes code that reads the same every time.** Before every edit, the
+  agent is nudged toward one shared checklist: guard clauses, braced
+  conditionals, fail fast, one responsibility per unit, no speculative
+  layers. Language-specific deltas for Java, PHP/Laravel, TypeScript,
+  Python, Go, and Rust load on demand — never dumped into the prompt.
+
+## What's inside
+
+### `sideroom_ask` — decisions, not interrogations
+
+One call is one 1–N question batch. Each question needs an `id`, a `prompt`,
+at least two `{ value, label }` options, and a `recommendationIndex` pointing
+at the recommended option. The UI adds the rest: the recommended mark, the
+always-on *Out of scope* row, and a custom answer.
+
+TUI-only by design. In print, JSON, or RPC modes it fails fast with
+`UI not available` instead of hanging.
+
+### `sideroom_todo` — a board, not a bureaucracy
+
+A display-only, ordered work board. The agent maintains it; you steer through
+chat. It never creates a repository task file or a `/todos` command.
+
+- `propose` replaces the full board (interactive TUI only).
+- `update` patches `{ id, status?, content? }` items and works everywhere,
+  including headless modes.
+- Invariant: while anything is pending, exactly one item is `in_progress`.
+
+### Edited files — proof, not promises
+
+Automatic tracking of successful `write` and `edit` results for the active
+session. The compact view shows at most five recent paths below an active
+board; the extended `F8` view scrolls through everything. Paths outside the
+project are labelled `external`. A new session starts clean.
+
+### Grill — settle the words first
+
+An on-demand skill for fuzzy plans. It interviews you in `sideroom_ask`
+rounds — reading the codebase first so it never asks what the code already
+says — until you share one understanding. Resolved terms land in
+`CONTEXT.md` the moment they resolve; hard decisions land as ADRs under
+`docs/adr/`. Everything else stays in the conversation, ready to become a
+spec or an implementation. Vocabulary sharpening during the rounds follows
+the companion `sideroom-domain-modeling` skill, which also runs on its own
+whenever the words — not the plan — are the problem. And when there is no
+one to interview at all, `sideroom-domain-scaffold` reads the central
+domain code as source of truth, builds or completes `CONTEXT.md` on its
+own, and grills the conflicting terms once, at the end.
+
+### Guidelines — a nudge, not a novel
+
+A short system-prompt reminder points at the packaged
+`sideroom-guidelines` skill. The skill body holds the shared Do/Don't table;
+one matching file under `skills/sideroom-guidelines/references/languages/`
+covers the language being edited. The canonical seed,
+`assets/artifacts/GUIDELINES_TEMPLATE.md`, is never pasted into the prompt.
 
 ## Quick path
 
-1. Install globally from npm. Pi writes this installation to your user
-   settings, so do not use `-l`.
+1. Install globally from npm. Pi records this in your user settings, so do
+   not use `-l`.
 
    ```bash
    pi install npm:@rmrdeveloper/sideroom-pi
    ```
 
 2. Start Pi in the repository you want to work in.
-3. Ask the parent agent a question that needs a decision or a visible work
-   board. It can call `sideroom_ask` or `sideroom_todo` in the TUI.
+3. Ask the parent agent something that needs a decision or a visible plan.
+   It calls `sideroom_ask` or `sideroom_todo` in the TUI.
 
-For a reproducible environment, pin a release. A pinned version does not move
-when you run Pi's package update command.
+Pin for reproducibility — a pinned version does not move on Pi's package
+update:
 
 ```bash
 pi install npm:@rmrdeveloper/sideroom-pi@7.0.0
 ```
 
-To update an unpinned installation:
+Update an unpinned installation with:
 
 ```bash
 pi update --extension npm:@rmrdeveloper/sideroom-pi
 ```
 
-## Details
+## Reference
 
-| Topic | Decision |
-| --- | --- |
-| Surface | Two LLM-callable tools: `sideroom_ask` and `sideroom_todo`. No `/sideroom` command. |
-| Questionnaire | One `sideroom_ask` call is one 1–N question batch; every question has `recommendationIndex`. |
-| Always-on rows | The questionnaire UI adds Out of scope and a custom answer. Do not send those options. |
-| Work board | `sideroom_todo propose` replaces a visible board; `update` patches items by id. |
-| Headless | `sideroom_todo update` works in print, JSON, and RPC. `propose` and `sideroom_ask` return `Error: UI not available` there. |
-| Edited files | Successful `write` and `edit` results appear below an active work board; `F8` opens the full list. |
-| Session state | The work board and edited-file history live in the Pi session branch, not in the target repository. |
-| Coding guidelines | A short system-prompt reminder points at the `sideroom-guidelines` skill. Language deltas load on demand. |
-| Seed artifact | `assets/artifacts/GUIDELINES_TEMPLATE.md` is the canonical seed; it is not dumped into the prompt. |
-
-## Tool
-
-`sideroom_ask` follows Pi's questionnaire UI: a simple list for one question,
-tabs plus Submit for several. Write prompts, tab labels, and option copy in
-the language the user is speaking; ids, option values, and TUI chrome stay
-English. Each question needs:
-
-- `id`
-- `prompt`
-- at least two `{ value, label, description? }` options
-- `recommendationIndex` pointing at the recommended option
-- optional `label` for the tab bar (defaults to `Q1`, `Q2`, …)
-
-The recommended option is marked in the list. Escape cancels the batch.
-
-## Work board
-
-`sideroom_todo` keeps an ordered, display-only board above the editor. The
-agent maintains it and the user steers through chat. It never creates a
-repository task file or a `/todos` command.
-
-- `propose` replaces the full board and is available only in the interactive
-  TUI.
-- `update` applies one or more `{ id, status?, content? }` patches and works in
-  every Pi mode.
-- Items have stable string ids, short content, and one of `pending`,
-  `in_progress`, `completed`, or `cancelled`.
-- While items are pending, exactly one item must be `in_progress`. Complete the
-  current item and start the next one in the same update.
-- Snapshots are stored in the active session branch. The board is rebuilt after
-  session navigation and compaction.
-
-## Edited files
-
-The package automatically records successful Pi `write` and `edit` calls for
-the active session. It does not infer filesystem changes from shell commands,
-Git, people, or subagents. The compact list is shown below the work board when
-one is active and contains at most five recent paths.
-
-- `F8` opens or closes the extended, scrollable list; press `R` there
-  to clear the current session's history.
-- Every path is an OSC 8 `file://` link. Your terminal determines whether that
-  is a click, Ctrl+click, or another modifier-assisted action.
-- Paths outside the active project are labelled `external`.
-- A new session starts with a new list; the current session's history survives
-  reload, tree navigation, and compaction.
+### Questionnaire contract
 
-## Coding guidelines
+Write prompts, tab labels, and option copy in the language the user is
+speaking; keep ids, option values, and TUI chrome in English. Do not send
+*Out of scope* or custom-answer rows yourself — the UI always adds them.
 
-Before `write` or `edit`, the parent agent is reminded to read the packaged
-`sideroom-guidelines` skill. That skill holds the shared Do/Don't table. For
-`.java`, `.php`, `.ts`/`.tsx`, `.py`, `.go`, and `.rs`, the agent also reads one
-matching file under `skills/sideroom-guidelines/references/languages/`. Other
-languages follow the shared table only.
+### Board contract
 
-## Development
+Items have stable string ids, short content, and one of `pending`,
+`in_progress`, `completed`, or `cancelled`. Complete the current item and
+start the next one in the same `update` call. Snapshots live in the active
+session branch and are rebuilt after navigation and compaction.
 
-```bash
-npm install
-npm run check
-```
+### Edited-files contract
 
-Biome is the sole formatter and linter. Pi loads TypeScript from `extensions/`
-directly; do not bundle. Pi provides `@earendil-works/pi-coding-agent`,
-`@earendil-works/pi-tui`, and `typebox` as peer dependencies.
+- Trigger: only successful Pi `write`/`edit` results.
+- Compact widget: max five paths, reapplied below the board.
+- Extended view: `F8` toggles, `R` clears session history.
+- Links: OSC 8 `file://` — click behavior depends on your terminal.
 
-## Releases and commits
+### Guidelines contract
 
-Commit messages must follow the Conventional Commits format. The existing
-Husky `commit-msg` hook validates each local commit with Commitlint, for
-example `feat: mark the recommended sideroom_ask option`.
+Read the skill before `write`/`edit`. Read at most one language delta per
+change — the one matching the path. Other languages follow the shared table
+only.
 
-Every user-visible package change needs a Changeset. Create one with:
+### Grill contract
 
-```bash
-npm run changeset
-```
+Load the skill at the start of a change with a fuzzy plan.
+Single-session scope only. Files are created lazily: nothing exists until
+the first term or decision crystallises. A session with a sharper glossary
+and zero ADRs is working as designed.
 
-Review pending release work with `npm run changeset:status`. When Changesets
-are merged to `main`, the `Release` workflow creates or updates a reviewable
-Changesets version PR. That PR contains the generated `package.json`,
-`package-lock.json`, and `CHANGELOG.md` updates. Merge the version PR only after
-review; its merge runs `npm ci` and `npm run check`, then uses
-npm 11.5.1 and npm Trusted Publishing (GitHub OIDC) to publish. Changesets then
-pushes the release Git tag and creates the GitHub Release automatically.
-
-Never run `npm publish`, create release tags, or create GitHub Releases locally.
-Publishing is allowed only through the merged Changesets version PR and the
-`Release` workflow. The npm package's Trusted Publisher must be configured for
-this GitHub repository, the workflow filename `release.yml` (not its path),
-and the `npm` environment; configure the matching GitHub `npm` environment
-before the first release.
-
-## Layout
-
-```text
-extensions/
-  ask/                   sideroom_ask (index.ts, execute.ts, model.ts, ui.ts)
-  todo/                  sideroom_todo (index.ts, execute.ts, session.ts,
-                         guards.ts, model.ts, ui.ts)
-  modified-files/        session-backed edited-file tracker and view
-  guidelines/            short write/edit reminder
-skills/sideroom-guidelines/  on-demand checklist and language deltas
-assets/artifacts/        GUIDELINES_TEMPLATE.md seed
-```
+## License
 
-Add another tool as `extensions/<name>/index.ts`. Pi discovers
-`extensions/*/index.ts`; helpers in that folder are not loaded as extensions.
+MIT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "7.0.1",
+  "version": "7.1.0",
   "description": "A global Pi package with a questionnaire, work board, edited-file view, and coding guidelines for parent agents.",
   "type": "module",
   "files": [

package/skills/sideroom-domain-modeling/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: sideroom-domain-modeling
+description: "Trigger: ubiquitous language, domain term, CONTEXT.md, ADR, vague word, naming conflict. Sharpen the project's domain language while designing: challenge vague terms, split overloaded ones, and write the settled vocabulary into the repo."
+license: MIT
+metadata:
+  author: RMRdeveloper
+  version: "1.0"
+---
+
+# Sideroom domain modeling
+
+## Activation Contract
+
+Load this skill when the _words_ are the problem: two people mean different
+things by one term, one term is doing several jobs, or a statement about the
+domain needs to survive longer than the conversation. This is the active
+discipline — changing the model — not the passive habit of reading
+`CONTEXT.md` to borrow a word. That read needs no skill; it is one line.
+
+It runs underneath `sideroom-grill` through a grilling session, and it also
+runs on its own when you want the discipline without the interview.
+
+## Hard Rules
+
+- Interrupt. When a term conflicts with the glossary, stop and ask which of
+  the two things is meant instead of picking one and moving on. When a vague
+  word appears where a precise one exists, force the precise word.
+- Stress-test relationships with a concrete scenario until the boundaries
+  are exact.
+- Cross-check statements against the code. When the code and the sentence
+  disagree, quote the code back and settle which one is right out loud,
+  before changing either.
+- A resolved term lands in `CONTEXT.md` the moment it resolves, inline, in
+  the middle of the conversation. One or two sentences saying what the thing
+  **is**, plus rejected synonyms under `_Avoid_`.
+- `CONTEXT.md` is a glossary and nothing else. Never persist implementation
+  details, spec prose, scratch notes, or general programming concepts there.
+  Refuse the write and say why.
+- An ADR under `docs/adr/` is offered, never assumed, and only when all
+  three gates pass at once: hard to reverse, surprising without context, and
+  the result of a real trade-off. When refusing, say which test failed.
+- Create files lazily. Nothing exists until the first term or decision
+  crystallises. In a repo with a `CONTEXT-MAP.md` at the root, terms go into
+  the per-context `CONTEXT.md` the map points at instead.
+- Keep the glossary lean. It gets shorter as often as it gets longer: split
+  an overloaded term, drop a dead one, and when the file has absorbed detail
+  that was never glossary material, offer to condense it.
+
+## Decision Gates
+
+| Situation | Move |
+| --- | --- |
+| Two meanings for one term | Pick the canonical term, list the other under `_Avoid_` |
+| One term doing several jobs | Split it (e.g. `Account` into `Customer` and `User`) |
+| A vague term became canonical | Write it to `CONTEXT.md` now |
+| A hard-to-reverse choice clearing all three ADR gates | Offer an ADR under `docs/adr/` |
+| The module's shape is the problem, not its words | This skill does not apply; that is module design |
+| The whole plan needs interrogating before building | `sideroom-grill`, which drives this skill underneath |
+| A term only needs looking up, not changing | Read `CONTEXT.md`. It is a file |
+
+## Execution Steps
+
+1. Read `CONTEXT.md` (and the ADRs, if any) before touching the model.
+2. As terms settle, write each one inline with its `_Avoid_` list.
+3. As hard choices surface, offer an ADR or refuse one with the failed
+   test named.
+4. Before finishing, re-read the touched entries: each defines what a thing
+   is, in one or two sentences, with no implementation detail.
+
+## Output Contract
+
+The repo holds the shared vocabulary and the hard decisions, each entry
+short enough to re-read. The glossary never becomes a running spec.
+
+## References
+
+- Driven by `sideroom-grill` during grilling sessions.
+- Entry rules reused by `sideroom-domain-scaffold` for code-first
+  scaffolding without interviews.
+- Based on the `domain-modeling` discipline described at
+  `https://www.aihero.dev/skills-domain-modeling`.

package/skills/sideroom-domain-scaffold/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: sideroom-domain-scaffold
+description: "Trigger: document my repo, scaffold CONTEXT.md, brownfield glossary, survey domain. Read the central domain code as source of truth and build or complete CONTEXT.md without interviewing anyone; conflicting terms are collected and grilled once, at the end."
+license: MIT
+metadata:
+  author: RMRdeveloper
+  version: "1.0"
+---
+
+# Sideroom domain scaffold
+
+## Activation Contract
+
+Load this skill on explicit request ("document my repo", "scaffold the
+glossary") over a codebase whose domain language is missing or thin. The
+code is the source of truth. Nobody is interviewed while the modeling runs.
+
+## Hard Rules
+
+- Zero interviews during the scan. Every irreconcilable conflict goes onto
+  a conflict list; modeling continues. The happy path is never interrupted.
+- Scope is the central business domain: its modules, types, enums, and
+  statuses. Ignore infrastructure, tooling, and utilities. Domain tests are
+  witnesses of the language, never sources of new terms.
+- Reconcile by prevalence and centrality: the dominant, core-module usage
+  wins. Record each such call as an assumption for later review.
+- Merge, never rebuild. An existing `CONTEXT.md` is curated truth: add and
+  sharpen only. A contradiction between the code and an existing entry is
+  not overwritten; it joins the conflict list.
+- Entry format, glossary purity, lazy file creation, and multi-context
+  routing all follow `sideroom-domain-modeling`. This skill owns the scan;
+  that one owns the writing.
+- No ADRs. Trade-offs cannot be validated without humans; hard choices found
+  in the code are reported, not recorded.
+- Grill once, at the end. When modeling is complete, launch
+  `sideroom-grill` scoped exactly to the conflict list so a human bounds
+  each confused term correctly. With an empty list there is no grill: close
+  with the glossary and the assumptions.
+
+## Decision Gates
+
+| Situation | Move |
+| --- | --- |
+| Same term, two meanings, no dominant use | Conflict list; grilled at the end |
+| Code contradicts an existing glossary entry | Conflict list; the entry stands until grilled |
+| Term belongs to infra, tooling, or utils | Skip it; out of scope |
+| Whole plan needs interrogating, not just terms | `sideroom-grill` instead of this skill |
+
+## Execution Steps
+
+1. Read `CONTEXT.md` (and `CONTEXT-MAP.md`, if any) before touching the
+   model.
+2. Survey the central domain code and collect candidate terms.
+3. Group synonyms, split overloaded terms, reconcile by prevalence.
+4. Write each settled term inline, merged with what exists.
+5. Collect conflicts and assumptions without stopping.
+6. Close: report the glossary and the assumptions, then either launch the
+   end-of-run `sideroom-grill` on the conflict list or state that the model
+   came out clean.
+
+## Output Contract
+
+A merged `CONTEXT.md` the code already agrees with, a reviewable list of
+assumptions, and — only when the code disagreed with itself — one bounded
+grilling at the end. No interview ever interrupts the scan.
+
+## References
+
+- Entry rules come from `sideroom-domain-modeling`.
+- Conflicts are handed to `sideroom-grill`, once, at the end of the run.

package/skills/sideroom-grill/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: sideroom-grill
+description: "Trigger: fuzzy plan, design review, grilling, CONTEXT.md, ADR, domain language. Interview the user in rounds until you share one understanding, then write the vocabulary and the hard decisions into the repo."
+license: MIT
+metadata:
+  author: RMRdeveloper
+  version: "1.0"
+---
+
+# Sideroom grill
+
+## Activation Contract
+
+Load this skill at the start of a change, in a repo, when the plan is still
+fuzzy and the words for the thing are not settled yet. Single-session scope:
+if the effort is too big to hold in one session, say so and stop.
+
+## Hard Rules
+
+- Interview in rounds. One `sideroom_ask` call is one round; wait for its
+  answers before the next round.
+- Every question carries a recommendation (`recommendationIndex`). Write
+  prompts and option copy in the language the user is speaking; keep ids and
+  option values in English.
+- Never ask the user what the codebase can answer. Read the code first; ask
+  only what the code cannot settle.
+- An *Out of scope* answer closes that thread. Do not re-ask it.
+- Everything a round settles is recorded through `sideroom-domain-modeling`:
+  inline glossary entries, the ADR three-gate offer, lazy file creation.
+  This skill owns the interview; that one owns the writing.
+- Everything that is neither glossary nor ADR lives in the conversation
+  only. Do not clear the session after grilling; hand it to a spec or
+  straight to implementation instead.
+
+## Execution Steps
+
+1. Read the code around the change. Settle from the codebase everything the
+   codebase settles.
+2. Run one `sideroom_ask` round on what remains genuinely open: terms first,
+   then decisions.
+3. After each round, write resolved terms to `CONTEXT.md` and qualifying
+   decisions to `docs/adr/`.
+4. Repeat until no open term or hard decision remains, or the user cancels.
+5. Close by stating the settled glossary, the ADRs written (if any), and the
+   suggested next step: a spec for anything non-trivial, implementation for
+   what is small enough to build now.
+
+## Output Contract
+
+The repo holds the shared vocabulary and the hard decisions; the
+conversation holds everything else. The user can re-read `CONTEXT.md` and
+the ADRs and find exactly what was agreed, nothing softened.
+
+## References
+
+- Drives `sideroom-domain-modeling` underneath: vocabulary sharpening
+  during the rounds follows that skill.
+- Closes `sideroom-domain-scaffold` runs: terms a scan could not reconcile
+  are grilled here, once, at the end.
+- Based on the `grill-with-docs` discipline described at
+  `https://www.aihero.dev/skills-grill-with-docs`.