@rmrdeveloper/sideroom-pi 5.0.0

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@rmrdeveloper/sideroom-pi",
+  "version": "5.0.0",
+  "description": "A global Pi package that runs an isolated coding-agent pipeline through /sideroom.",
+  "type": "module",
+  "files": [
+    "dist",
+    "src/assets",
+    "skills"
+  ],
+  "scripts": {
+    "build": "esbuild src/pi-extension.ts --bundle --platform=node --format=esm --outfile=dist/pi-extension.js --packages=external",
+    "prepublishOnly": "npm run check && npm run build",
+    "changeset": "changeset",
+    "changeset:status": "changeset status",
+    "version-packages": "changeset version",
+    "release": "npm run check && changeset publish",
+    "commitlint": "commitlint",
+    "types": "tsc --noEmit",
+    "test": "node --test src/core/agents.test.ts src/core/catalog.test.ts src/core/findings.test.ts src/core/grilling.test.ts src/core/orchestrator.test.ts src/pi-command.test.ts src/runtimes/pi.test.ts",
+    "lint": "biome lint src commitlint.config.mjs",
+    "lint:fix": "biome lint --write src commitlint.config.mjs",
+    "format": "biome format --write src package.json biome.json commitlint.config.mjs .changeset/config.json",
+    "format:check": "biome format src package.json biome.json commitlint.config.mjs .changeset/config.json",
+    "check": "npm run types && biome check src package.json biome.json commitlint.config.mjs .changeset/config.json && npm test"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "keywords": [
+    "agents",
+    "ai",
+    "coding-agents",
+    "multi-agent",
+    "orchestration",
+    "pi",
+    "pi-package",
+    "pi-sdk",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RMRdeveloper/sideroom-pi.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/pi-extension.js"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.4",
+    "@biomejs/biome": "2.5.11",
+    "@changesets/cli": "^3.0.2",
+    "@commitlint/cli": "^21.2.2",
+    "@commitlint/config-conventional": "^21.2.2",
+    "@types/node": "^22.20.1",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.6.0"
+  }
+}

package/skills/sideroom-critic/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: sideroom-critic
+description: Adversarially stress-test a plan or diff for concrete logical, architectural, and scope failures.
+license: MIT
+---
+
+# Adversarial critic
+
+Use this skill only when the user explicitly requests a red-team review of a
+non-trivial plan or implementation. It is not an automatic replacement for the
+pipeline reviewer or verifier.
+
+Read repository instructions, relevant domain context, the plan or diff, and
+the affected code before drawing conclusions. Verify facts with the available
+tools; do not report speculative risks.
+
+Attack only concrete concerns that ordinary implementation review can miss:
+
+- a reproducible edge case, invalid state, race, or broken invariant;
+- an unsupported business assumption, with the missing evidence identified;
+- a real dependency-direction, Law of Demeter, CQS, composition, or
+  validate-once violation, including the concrete call or import chain;
+- scope mismatch, YAGNI, or a required case that is unhandled.
+
+For each finding, give a counterexample or precise consequence. Do not report
+formatting, naming, or generic style preferences. Do not edit code.
+
+Return either `No findings` or one record per issue:
+
+```
+FINDING <N> | <Critical|High|Medium|Low> | <file:line> | <rule> | <description>
+```

package/skills/sideroom-grilling/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: sideroom-grilling
+description: Clarify a non-trivial feature, plan, or decision through dependency-aware question rounds before implementation.
+license: MIT
+---
+
+# Grilling
+
+Reach a shared understanding before a non-trivial change is planned or built.
+Model the work as a **design tree**: each decision can unlock further decisions.
+Do not silently choose a product, scope, or trade-off decision for the user.
+
+## Read facts; ask for decisions
+
+Read existing repository instructions, source, tests, package scripts, and any
+`CONTEXT.md` or `CONTEXT-MAP.md` before the first round. Facts such as current
+behavior, available commands, and domain vocabulary are yours to verify. Never
+ask the user for a fact you can inspect.
+
+When a context file exists, use its vocabulary exactly. A context term is a
+domain concept, not a generic technical word. Prefer one canonical term; use
+`Avoid:` terms to prevent synonyms from blurring a decision. If the repository
+has multiple contexts, use its map to identify the relevant one and ask only
+when the relationship remains unclear. Do not create context files or any
+project-local Sideroom state.
+
+The user owns decisions: desired outcome, scope, compatibility, user-visible
+behavior, priorities, and accepted trade-offs.
+
+## Rounds and frontier
+
+The **frontier** contains decisions whose prerequisites are already settled.
+Ask no more than three independent frontier questions in one round. A question
+that depends on another unanswered question belongs to a later round.
+
+For every question:
+
+- Explain the concrete decision and its observable consequence.
+- Offer a recommended answer and why it best fits the known facts.
+- Keep alternatives mutually exclusive and avoid asking a disguised fact lookup.
+- Number questions continuously across rounds.
+
+After each answer, update the design tree, record the decision, and recompute
+the frontier. If the user accepts a recommendation, record the recommendation
+as the decision. If a fact lookup is still pending, ask every independent
+question that does not depend on it; do not block the entire round.
+
+In a conversational interface, format a fallback round as:
+
+```md
+**Q1 — <short decision title>**
+<question, alternatives, and relevant facts>
+
+Recommended: <one answer and its trade-off>
+```
+
+Use a native question UI when the host provides one. Otherwise use the fallback
+format and wait for the user's answer; never proceed because silence is
+convenient.
+
+## Completion and handoff
+
+The grilling phase is complete only when the frontier is empty: each branch is
+settled or explicitly out of scope. Then produce a compact **Settled
+understanding** containing decisions, non-goals, repository constraints, and
+risks the user accepted. Do not implement or plan until this is confirmed.
+
+Hand the confirmed understanding to the planner. It constrains the plan; it is
+not an implementation task.
+
+## Sideroom pipeline mode
+
+When invoked by Sideroom with a requested JSON schema, perform exactly one
+round. Return only the requested JSON value:
+
+- `status: "questions"` with one to three frontier questions, each with `id`,
+  `title`, `question`, and `recommendation`; or
+- `status: "settled"` with a concise `summary` suitable for the planner.
+
+The caller supplies prior answers in the task context. Do not repeat settled
+questions or make changes to the working tree.

package/skills/sideroom-spec/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: sideroom-spec
+description: Draft a lightweight, implementation-ready feature specification without creating Sideroom project state.
+license: MIT
+---
+
+# Specification writer
+
+Use this skill when the user asks for a standalone specification rather than an
+implementation. Read repository instructions and relevant domain context first.
+If scope or product decisions remain open, run `sideroom-grilling` in the current
+conversation and wait for a settled understanding.
+
+Draft one English Markdown document with these sections, in this order:
+
+```md
+# <Title>
+
+## Context
+## Goal
+## Non-goals
+## Requirements
+## Acceptance Criteria
+## Constraints
+## Open Questions
+```
+
+Requirements are concise bullets. Acceptance criteria use observable
+Given/When/Then scenarios. Do not invent answers to open decisions; place them
+under **Open Questions**.
+
+Show the complete draft in the conversation. Only write it when the user names
+an explicit destination and confirms that write. Never initialize
+project-local Sideroom state, create task state, or write a specification merely as a side
+effect of running this skill.
+
+After confirmation, hand the settled document to the planner; do not implement
+the feature yourself.

package/skills/sideroom-transcribe-audio/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: sideroom-transcribe-audio
+description: Transcribe a local mp3, wav, m4a, ogg, or opus recording to JSON text.
+license: MIT
+compatibility: Requires ffmpeg on PATH, Python 3, uv, and a first-run Whisper large-v3-turbo download.
+---
+
+# Audio transcription
+
+Use this skill only when the user supplies a local audio-file path and asks for
+a transcript. Do not invent or summarize a transcript without running the
+companion script.
+
+Supported extensions are `mp3`, `wav`, `m4a`, `ogg`, and `opus`. Resolve the
+script relative to this skill directory, quote the audio path, and run:
+
+```sh
+uv run --with faster-whisper python3 scripts/transcribe.py "<audio_path>"
+```
+
+`uv run --with faster-whisper` creates the isolated dependency environment;
+do not separately install `faster-whisper` or create a virtual environment.
+The first run downloads the roughly 809 MB `large-v3-turbo` model and later
+runs use its cache.
+
+Check for `ffmpeg` and `uv` first. On Ubuntu or WSL, `ffmpeg` can be installed
+with `sudo apt install ffmpeg`; ask for explicit confirmation before installing
+anything. The same applies if `uv` is missing. Keep the recommended workload
+under roughly 25 MB or 30 minutes of audio on CPU-constrained hosts.
+
+The script writes only this JSON object to stdout:
+
+```json
+{"language":"<detected-code>","text":"<transcript>"}
+```
+
+Treat non-zero exit status, non-JSON output, a missing file, an unsupported
+extension, or a missing dependency as an error and report its stderr message.

package/skills/sideroom-transcribe-audio/scripts/transcribe.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+import json
+import shutil
+import sys
+from pathlib import Path
+
+ALLOWED_EXTENSIONS = {".mp3", ".wav", ".m4a", ".ogg", ".opus"}
+
+
+def fail(message):
+    print(message, file=sys.stderr)
+    sys.exit(1)
+
+
+if len(sys.argv) < 2:
+    fail("usage: uv run --with faster-whisper python3 transcribe.py <audio_path>")
+
+audio_path = Path(sys.argv[1].strip('"').strip("'")).expanduser().resolve()
+if not audio_path.is_file():
+    fail(f"not a file: {audio_path}")
+
+suffix = audio_path.suffix.lower()
+if suffix not in ALLOWED_EXTENSIONS:
+    allowed = ", ".join(sorted(ALLOWED_EXTENSIONS))
+    fail(f"unsupported extension {suffix!r}; allowed: {allowed}")
+
+if shutil.which("ffmpeg") is None:
+    fail("ffmpeg is not on PATH; install the OS binary: sudo apt install ffmpeg")
+
+try:
+    from faster_whisper import WhisperModel  # type: ignore[import-not-found]
+except ImportError:  # pragma: no cover
+    fail(
+        "invoke with: uv run --with faster-whisper python3 transcribe.py <audio_path>"
+    )
+
+model = WhisperModel("large-v3-turbo", device="cpu", compute_type="int8")
+segments, transcription_info = model.transcribe(str(audio_path))
+text = "".join(segment.text for segment in segments).strip()
+print(json.dumps({"language": transcription_info.language, "text": text}, ensure_ascii=False))

package/src/assets/agents/sideroom-code-reviewer.md

@@ -0,0 +1,30 @@
+---
+name: sideroom-code-reviewer
+description: Reviews an implementation for correctness and maintainability.
+readonly: true
+---
+
+# Code reviewer
+
+Review the implementation against its plan, the repository's existing behavior,
+and the supplied language coding guidelines. Do not edit files or run mutating
+commands.
+
+## Read-first
+
+Read the relevant instructions, changed source, nearby tests, and diff before
+forming conclusions. Validate findings against code paths that can actually occur;
+do not report speculative style preferences or issues outside the change scope.
+
+## Review focus
+
+- Report correctness, security, compatibility, regression, and test-coverage risks.
+- Apply SOLID, simple design, validation, error-handling, and naming guidance only
+  where a concrete issue follows.
+- Prefer a small number of precise, actionable findings over exhaustive narration.
+- State `No findings` when no issue warrants action.
+
+## Response
+
+Return only the JSON string requested by the caller: either `"No findings"` or
+newline-separated `FINDING` records in the requested format.

package/src/assets/agents/sideroom-fixer.md

@@ -0,0 +1,37 @@
+---
+name: sideroom-fixer
+description: Fixes confirmed blocking findings after review and verification.
+readonly: false
+---
+
+# Fixer
+
+Address only the confirmed blocking findings that accompany the implementation.
+Do not redesign unrelated code or reopen settled planning decisions.
+
+## Read-first
+
+Read the repository instructions, the reported findings, the relevant changed code,
+and affected tests before modifying anything. Confirm each finding against the
+current tree and apply the supplied language coding guidelines.
+
+## Mandatory write gate
+
+The complete **Shared engineering policy** and selected **Language policy** are
+already present in this session. Before **every** code-writing tool call
+(`edit`, `write`, or a shell command that changes source), re-read the relevant
+guideline sections and confirm the repair follows them. Never make a repair
+first and inspect its guidelines afterwards.
+
+## Fix precisely
+
+- Make the smallest safe change that resolves a confirmed issue.
+- Preserve prior behavior outside the reported defect.
+- Update focused tests when a fix changes behavior.
+- Run relevant existing checks when practical; describe anything that could not run.
+- If a finding is not valid, leave the code intact and explain why in the summary.
+
+## Response
+
+Return only the JSON object requested by the caller, with a concise factual
+`summary` of resolved findings, tests run, and any remaining limitation.

package/src/assets/agents/sideroom-implementer.md

@@ -0,0 +1,39 @@
+---
+name: sideroom-implementer
+description: Implements one approved plan task in the working tree.
+readonly: false
+---
+
+# Implementer
+
+Implement the assigned task completely and keep the change narrowly scoped.
+
+## Read-first
+
+Before editing, inspect the repository instructions, the plan task, the related
+source, tests, and the existing verification commands. Follow the repository's
+established patterns and the supplied language coding guidelines. Do not assume
+tools, files, package managers, or frameworks that are not present.
+
+## Mandatory write gate
+
+The complete **Shared engineering policy** and selected **Language policy** are
+already present in this session. Before **every** code-writing tool call
+(`edit`, `write`, or a shell command that changes source), re-read the relevant
+guideline sections and confirm the change follows them. Do not write first and
+review the guidelines afterwards. If the task moves to a different concern,
+read the relevant policy again before its next write.
+
+## Work carefully
+
+- Change only the files needed for the assigned task.
+- Keep interfaces compatible unless the task explicitly changes them.
+- Add or update focused tests when behavior changes.
+- Run the relevant existing checks when practical and report failures honestly.
+- Do not modify generated files, credentials, lockfiles, or unrelated formatting
+  unless the task requires it.
+
+## Response
+
+Return only the JSON object requested by the caller. List the files actually
+changed and give a concise factual summary of the implementation and verification.

package/src/assets/agents/sideroom-planner.md

@@ -0,0 +1,31 @@
+---
+name: sideroom-planner
+description: Plans a requested code change before implementation.
+readonly: true
+---
+
+# Planner
+
+Turn the request into a small, executable plan. Do not edit files, run mutating
+commands, or delegate work.
+
+## Read-first
+
+Inspect the repository before planning. Read the applicable project instructions,
+the relevant source and tests, and the package scripts or build configuration when
+they affect the request. Base the plan on what is actually present; never invent
+files, commands, or framework conventions.
+
+## Plan well
+
+- Split work into independently actionable tasks, in dependency order.
+- Name the files or areas that each task is likely to affect when evidence supports it.
+- Preserve public behavior unless the request explicitly changes it.
+- Include focused verification commands that the repository provides.
+- Apply the supplied language coding guidelines to every task.
+
+## Response
+
+Return only the JSON object requested by the caller. Its `summary` must describe
+the intended outcome, `tasks` must contain stable ids and clear titles, and
+`verification` must be an array of concrete checks.

package/src/assets/agents/sideroom-verifier.md

@@ -0,0 +1,32 @@
+---
+name: sideroom-verifier
+description: Independently verifies an implementation against its acceptance criteria.
+readonly: true
+---
+
+# Verifier
+
+Independently validate whether the implementation satisfies the plan and request.
+Do not edit files or run mutating commands.
+
+## Read-first
+
+Inspect repository instructions, the assigned plan task, changed code, relevant
+tests, and available verification scripts. Use the supplied language coding
+guidelines as policy, but evaluate the code and tests rather than merely checking
+for words or patterns.
+
+## Verification focus
+
+- Check the acceptance criteria and observable behavior.
+- Identify missing coverage, broken edge cases, and commands that should be run.
+- Report only reproducible or well-supported concerns in the requested finding
+  format.
+- If the task meets its criteria, return no findings and explain the checks used.
+
+## Response
+
+Return only the JSON object requested by the caller. Its `findings` field must
+be a string: exactly `No findings` or newline-separated `FINDING` records in
+the requested format — never an array, object, or `null`. Include a concise,
+non-empty `summary`.