@rmrdeveloper/sideroom-pi 5.0.0 → 6.0.1

package/skills/sideroom-critic/SKILL.md

@@ -1,32 +0,0 @@
----
-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

@@ -1,81 +0,0 @@
----
-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

@@ -1,38 +0,0 @@
----
-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

@@ -1,38 +0,0 @@
----
-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

@@ -1,40 +0,0 @@
-#!/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

@@ -1,30 +0,0 @@
----
-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

@@ -1,37 +0,0 @@
----
-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

@@ -1,39 +0,0 @@
----
-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

@@ -1,31 +0,0 @@
----
-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

@@ -1,32 +0,0 @@
----
-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`.

package/src/assets/artifacts/guidelines/java.md

@@ -1,211 +0,0 @@
-# Java Coding Guidelines
-
-This is the Java version of `GUIDELINES_TEMPLATE.md`. It preserves the same
-principles and example scenarios using explicit Java types, immutable values,
-and layered application boundaries. The shared baseline remains mandatory.
-
-## Quick reference
-
-| Do | Don't |
-| --- | --- |
-| Guard invalid input early | Bury happy paths in nested `if/else` branches |
-| Throw a precise exception now | Substitute a default and hide invalid state |
-| Give a class one responsibility | Validate, transform, persist, and notify together |
-| Extract repeated domain behavior | Add a hierarchy for a one-off method |
-| Build only current behavior | Add speculative flags and configuration |
-| Prefer immutable records/value objects | Mutate data passed by a caller |
-| Validate once at an adapter | Re-validate the same command in every layer |
-| Depend on ports at real seams | Construct database/HTTP clients in domain code |
-
-## Principles
-
-### Guard clauses
-
-The discount example keeps the happy path shallow.
-
-```java
-double getDiscount(User user) {
-    if (user == null) return 0.0;
-    if (!user.active()) return 0.0;
-    if (!user.hasSubscription()) return 0.0;
-    return 0.2;
-}
-```
-
-### Fail fast
-
-An unknown shipping zone is invalid state, not a reason to use a default.
-
-```java
-int shippingCost(String zoneId, Map<String, Zone> zones) {
-    var zone = zones.get(zoneId);
-    if (zone == null) throw new IllegalArgumentException("Unknown zoneId: " + zoneId);
-    return zone.baseCost();
-}
-```
-
-### SRP
-
-The user flow separates normalization, repository work, and notification.
-
-```java
-final class CreateUser {
-    private final UserRepository users;
-    private final Mailer mailer;
-    User create(String email) {
-        if (email.isBlank()) throw new IllegalArgumentException("email required");
-        var user = users.save(new User(normalizeEmail(email)));
-        mailer.send(user.email(), "welcome");
-        return user;
-    }
-    private String normalizeEmail(String email) { return email.trim().toLowerCase(Locale.ROOT); }
-}
-```
-
-### DRY
-
-Extract the third repeated ticket-status normalization, not a premature helper.
-
-```java
-enum TicketStatus { OPEN, CLOSED }
-TicketStatus normalizeTicketStatus(String value) { return TicketStatus.valueOf(value.toUpperCase(Locale.ROOT)); }
-```
-
-### KISS
-
-Keep price and invoice examples limited to today's scope.
-
-```java
-String formatPrice(BigDecimal value) { return "$" + value.setScale(2); }
-```
-
-### YAGNI (You Aren't Gonna Need It)
-
-Build the invoice requirement that exists today. Do not add currency strategies,
-recurring branches, event listeners, or cache layers without a real requirement.
-
-```java
-Invoice createInvoice(Order order) { return new Invoice(order.total(), order.items()); }
-```
-
-### Composition over inheritance
-
-Compose behavior rather than inherit an irrelevant `fly()` operation.
-
-```java
-record Dog(BarkBehavior bark) { String makeSound() { return bark.sound(); } }
-interface BarkBehavior { String sound(); }
-```
-
-### Law of Demeter
-
-Ask the user for its city, not its address's city's name.
-
-```java
-String cityName(User user) { return user.cityName(); }
-```
-
-### Command Query Separation
-
-Peeking and incrementing a counter are separate methods.
-
-```java
-int peekNextId(Counter counter) { return counter.value() + 1; }
-void incrementCounter(Counter counter) { counter.increment(); }
-```
-
-### Explicit error handling
-
-Retain a cause and add user-specific context; do not catch and return null.
-
-```java
-User loadUser(String id, UserApi api) {
-    try { return api.get(id); }
-    catch (ApiException error) { throw new IllegalStateException("Failed to load user " + id, error); }
-}
-```
-
-### Immutability by default
-
-The cart scenario returns a new record.
-
-```java
-record Cart(List<Item> items) {}
-Cart addItem(Cart cart, Item item) {
-    var items = new ArrayList<>(cart.items());
-    items.add(item);
-    return new Cart(List.copyOf(items));
-}
-```
-
-### Null handling
-
-Prefer explicit absence with `Optional` at boundaries and preserve a zero
-discount as a real value.
-
-```java
-double getDiscount(Optional<User> user) {
-    return user.flatMap(User::plan).map(Plan::discount).orElse(0.0);
-}
-```
-
-### Testability as a design constraint
-
-Inject `Clock` instead of asking the system clock inside domain behavior.
-
-```java
-boolean isSubscriptionExpired(Subscription subscription, Clock clock) {
-    return subscription.expiresAt().isBefore(Instant.now(clock));
-}
-```
-
-### Dependency direction
-
-Invoice calculation receives an invoice rather than an SQL/JPA dependency.
-
-```java
-int calculateInvoiceTotal(Invoice invoice) {
-    return invoice.items().stream().mapToInt(InvoiceItem::price).sum();
-}
-```
-
-### Clear names
-
-Use `activeSubscriptions`, `remainingDays`, and `externalId`, never `data`,
-`temp`, or `obj`.
-
-### Comments
-
-Comments explain a delivery trade-off or an idempotency hazard, not a statement
-whose name already explains it.
-
-### No magic strings
-
-Model order states as an enum.
-
-```java
-enum OrderStatus { PENDING_PAYMENT, PAID }
-if (order.status() == OrderStatus.PENDING_PAYMENT) payments.request(order);
-```
-
-### SOLID
-
-The welcome use case depends on a mailer port, not SMTP.
-
-```java
-interface Mailer { void send(String email, String template); }
-final class SendWelcomeEmail { private final Mailer mailer; SendWelcomeEmail(Mailer mailer) { this.mailer = mailer; } }
-```
-
-### Validate once
-
-An HTTP/message adapter builds a validated command. The application service
-trusts it and never repeats the same null, type, and range checks.
-
-```java
-record UpdateProfile(String email) {}
-void updateProfile(UpdateProfile command, UserRepository users) { users.update(command); }
-```
-
-Use one validation contract per body/query. When in doubt: **fail fast, keep it
-flat, keep it small.**