@rmrdeveloper/sideroom-pi 6.0.1 → 7.0.0

package/README.md

@@ -7,9 +7,10 @@
 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.
-It writes no `.pi` configuration, task graph, or other Sideroom files into the
-repository you are working in.
+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.
 
 ## Quick path
 
@@ -48,12 +49,15 @@ pi update --extension npm:@rmrdeveloper/sideroom-pi
 | 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. |
-| Seed artifact | `assets/artifacts/GUIDELINES_TEMPLATE.md` ships unwired. |
+| 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. English copy. Each question needs:
+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`
@@ -95,6 +99,14 @@ one is active and contains at most five recent paths.
 - A new session starts with a new list; the current session's history survives
   reload, tree navigation, and compaction.
 
+## Coding guidelines
+
+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.
+
 ## Development
 
 ```bash
@@ -141,7 +153,9 @@ extensions/
   todo/                  sideroom_todo (index.ts, execute.ts, session.ts,
                          guards.ts, model.ts, ui.ts)
   modified-files/        session-backed edited-file tracker and view
-assets/artifacts/        unwired GUIDELINES_TEMPLATE.md seed
+  guidelines/            short write/edit reminder
+skills/sideroom-guidelines/  on-demand checklist and language deltas
+assets/artifacts/        GUIDELINES_TEMPLATE.md seed
 ```
 
 Add another tool as `extensions/<name>/index.ts`. Pi discovers

package/extensions/ask/index.ts

@@ -4,14 +4,15 @@ import { executeAsk } from './execute.ts';
 import { AskParamsSchema, type AskResult, TOOL_NAME } from './model.ts';
 
 export const ASK_DESCRIPTION =
-  'Ask the user one or more questions. Use for clarifying requirements, getting preferences, or confirming decisions. Each question must include a recommended option. For a single question, shows a simple option list. For multiple questions, shows a tab-based interface.';
+  'Ask the user one or more questions in the language they are speaking. Use for clarifying requirements, getting preferences, or confirming decisions. Each question must include a recommended option. For a single question, shows a simple option list. For multiple questions, shows a tab-based interface.';
 
 export const ASK_PROMPT_SNIPPET =
-  'Ask the user one or more questions with a recommended option.';
+  'Ask the user one or more questions with a recommended option, in their language.';
 
 export const ASK_PROMPT_GUIDELINES = [
   'Use sideroom_ask to clarify requirements, preferences, or decisions with the user.',
   'Each sideroom_ask question needs an id, a prompt, at least two options, and a recommendationIndex pointing at the recommended option.',
+  'Write every sideroom_ask prompt, tab label, and option label or description in the language the user is speaking. Keep ids, option values, and tool code in English.',
   'sideroom_ask always adds Out of scope and a custom answer; do not include those options yourself.',
   'One sideroom_ask call is one batch; call it again if another round of questions is needed.',
   'sideroom_ask only works in the interactive TUI; it returns an error in print, JSON, or RPC modes.',

package/extensions/guidelines/index.ts

@@ -0,0 +1,13 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { appendGuidelinesReminder } from './prompt.ts';
+
+// Pi loads extensions/*/index.ts through export default.
+export default function registerGuidelines(pi: ExtensionAPI): void {
+  pi.on('before_agent_start', (event) => {
+    const systemPrompt = appendGuidelinesReminder(event.systemPrompt);
+    if (systemPrompt === event.systemPrompt) {
+      return;
+    }
+    return { systemPrompt };
+  });
+}

package/extensions/guidelines/prompt.ts

@@ -0,0 +1,26 @@
+export const GUIDELINES_REMINDER_HEADING =
+  'Sideroom coding guidelines (always-on reminder):';
+
+export const GUIDELINES_REMINDER = `${GUIDELINES_REMINDER_HEADING}
+Before write or edit, read the sideroom-guidelines skill.
+Apply its Do/Don't table. If the path is .java, .php, .ts/.tsx, .py, .go, or .rs, also read that language file under the skill's references/languages/.
+Do not load other language files.`;
+
+export const LANGUAGE_DELTA_FILES = [
+  'go.md',
+  'java.md',
+  'php-laravel.md',
+  'python.md',
+  'rust.md',
+  'typescript.md',
+] as const;
+
+export function appendGuidelinesReminder(systemPrompt: string): string {
+  if (systemPrompt.includes(GUIDELINES_REMINDER_HEADING)) {
+    return systemPrompt;
+  }
+  if (systemPrompt.length === 0) {
+    return GUIDELINES_REMINDER;
+  }
+  return `${systemPrompt}\n\n${GUIDELINES_REMINDER}`;
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "6.0.1",
-  "description": "A global Pi package with a questionnaire, work board, and edited-file view for parent agents.",
+  "version": "7.0.0",
+  "description": "A global Pi package with a questionnaire, work board, edited-file view, and coding guidelines for parent agents.",
   "type": "module",
   "files": [
     "extensions",
     "assets",
+    "skills",
     "!extensions/**/*.test.ts"
   ],
   "scripts": {
@@ -35,6 +36,7 @@
     "edited-files",
     "sideroom_ask",
     "sideroom_todo",
+    "guidelines",
     "typescript"
   ],
   "license": "MIT",
@@ -48,6 +50,9 @@
   "pi": {
     "extensions": [
       "./extensions"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "peerDependencies": {

package/skills/sideroom-guidelines/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: sideroom-guidelines
+description: "Trigger: write, edit, coding, Java, Laravel, TypeScript, Python, Go, Rust. Apply Sideroom coding principles before changing code."
+license: MIT
+metadata:
+  author: RMRdeveloper
+  version: "1.0"
+---
+
+# Sideroom guidelines
+
+## Activation Contract
+
+Load this skill before `write` or `edit`. Load at most one file from `references/languages/` for the path being changed.
+
+## Hard Rules
+
+- Follow the Do/Don't table. Language files override syntax and framework idiom only.
+- Do not load language files you are not editing this turn.
+- Fail fast, keep control flow flat, and validate once at the boundary.
+
+## Decision Gates
+
+| Path | Read |
+|------|------|
+| `.java` | `references/languages/java.md` |
+| `.php` | `references/languages/php-laravel.md` |
+| `.ts` `.tsx` | `references/languages/typescript.md` |
+| `.py` | `references/languages/python.md` |
+| `.go` | `references/languages/go.md` |
+| `.rs` | `references/languages/rust.md` |
+| other | shared table only |
+
+## Execution Steps
+
+1. Apply the table to the change.
+2. Read the matching language file, if any.
+3. Ship the smallest change that satisfies the current requirement.
+
+## Do / Don't
+
+| Do | Don't |
+| --- | --- |
+| Braces around every `if` body (Python: a full indented suite) | Unbraced or one-line conditional bodies |
+| Early return on bad input | Pyramid `if/else` nesting |
+| Explicit error, fail now | Fallbacks that hide the real failure |
+| One responsibility per unit | Validate + transform + persist + notify together |
+| Extract when duplication repeats | Abstract before a second real use |
+| Simplest solution for the current problem | Layers, hooks, or config "just in case" |
+| Build only what is needed today | Fields or branches for a future case |
+| Compose small focused units | Deep inheritance for unrelated behavior |
+| Talk only to immediate collaborators | Reach through another object's internals |
+| A function either does or returns, not both | Side effects inside a getter |
+| Validate once at the edge | Re-check the same invariant inward |
+| One validator per input | Two validators for the same body/query |
+| Let errors surface with context | Empty `catch` or catch-and-continue |
+| Return new values instead of mutating input | Mutate parameters |
+| One meaning per null/undefined | Overload null for several business states |
+| Inject dependencies | Hardcode infra that blocks tests |
+| Inner layers depend on nothing outward | Domain imports of DB/HTTP/framework types |
+| Names that reveal role or domain meaning | `data`, `info`, `temp`, `result`, `obj` |
+| Named const/enum/contract for domain literals | Magic strings |
+| Depend on ports where variation is real | Couple a use case to a concrete implementation |
+| Comments only for non-obvious intent | Narration, noise, or stale TODOs |
+
+## Output Contract
+
+Changed code follows the table and the loaded language delta. No extra files, layers, or comments unless the change requires them.
+
+## References
+
+- `references/languages/java.md`
+- `references/languages/php-laravel.md`
+- `references/languages/typescript.md`
+- `references/languages/python.md`
+- `references/languages/go.md`
+- `references/languages/rust.md`

package/skills/sideroom-guidelines/references/languages/go.md

@@ -0,0 +1,27 @@
+# Go
+
+Delta only. Keep the shared table.
+
+- Braces on every `if`. Keep `err` checks as flat guard clauses; do not nest the happy path.
+- Return errors with context. Do not `panic` for expected business failure, and do not ignore `err`.
+- Do not mutate slices or maps passed in as input; return a new value.
+
+```go
+// Bad
+func loadUser(id string) (*User, error) {
+    user, err := repo.Get(id)
+    if err == nil {
+        return user, nil
+    }
+    return nil, nil
+}
+
+// Good
+func loadUser(id string) (*User, error) {
+    user, err := repo.Get(id)
+    if err != nil {
+        return nil, fmt.Errorf("load user %s: %w", id, err)
+    }
+    return user, nil
+}
+```

package/skills/sideroom-guidelines/references/languages/java.md

@@ -0,0 +1,24 @@
+# Java
+
+Delta only. Keep the shared table.
+
+- Braces on every `if` / `else`, including one-line guards.
+- Fail fast with a clear exception. Do not hide a missing value behind a silent default.
+- Domain code depends on ports, not `new` of infrastructure types.
+
+```java
+// Bad
+public int shippingCost(Order order) {
+    Zone zone = zones.getOrDefault(order.zoneId(), Zone.DEFAULT);
+    return zone.baseCost();
+}
+
+// Good
+public int shippingCost(Order order) {
+    Zone zone = zones.get(order.zoneId());
+    if (zone == null) {
+        throw new IllegalArgumentException("Unknown zoneId: " + order.zoneId());
+    }
+    return zone.baseCost();
+}
+```

package/skills/sideroom-guidelines/references/languages/php-laravel.md

@@ -0,0 +1,26 @@
+# PHP / Laravel
+
+Delta only. Keep the shared table.
+
+- Braces on every `if` / `else`.
+- `FormRequest` (or one equivalent boundary) is the single validator. Services trust that contract and do not re-check the same rules.
+- Keep Eloquent/HTTP types out of domain logic.
+
+```php
+// Bad — Service repeats the FormRequest rule
+class ProfileService {
+    public function update(array $data) {
+        if (empty($data['email'])) {
+            throw new \InvalidArgumentException('email required');
+        }
+        $this->user->update($data);
+    }
+}
+
+// Good — Service trusts validated input
+class ProfileService {
+    public function update(array $validated) {
+        $this->user->update($validated);
+    }
+}
+```

package/skills/sideroom-guidelines/references/languages/python.md

@@ -0,0 +1,21 @@
+# Python
+
+Delta only. Keep the shared table.
+
+- Use a complete indented suite for every `if` / `else`. Never a one-line conditional body.
+- Treat `None` as "not set" or "explicitly empty" — pick one meaning and keep it. Do not use `None` for a real business state that deserves its own value.
+- Prefer returning new collections over mutating a caller's list or dict.
+
+```python
+# Bad
+def get_discount(user):
+    if user: return 0.2 if user.is_active else 0
+
+# Good
+def get_discount(user):
+    if user is None:
+        return 0
+    if not user.is_active:
+        return 0
+    return 0.2
+```

package/skills/sideroom-guidelines/references/languages/rust.md

@@ -0,0 +1,19 @@
+# Rust
+
+Delta only. Keep the shared table.
+
+- Prefer `Result` and `?`. Do not `.unwrap()` / `.expect()` in library or production paths.
+- Let errors surface with context (`map_err`, `anyhow`, or an equivalent). Do not swallow with `let _ =`.
+- Do not mutate the caller's value when returning a new one is enough.
+
+```rust
+// Bad
+fn load_user(id: &str) -> User {
+    repo.get(id).unwrap()
+}
+
+// Good
+fn load_user(id: &str) -> Result<User, LoadUserError> {
+    repo.get(id).map_err(|err| LoadUserError::from_repo(id, err))
+}
+```

package/skills/sideroom-guidelines/references/languages/typescript.md

@@ -0,0 +1,30 @@
+# TypeScript
+
+Delta only. Keep the shared table.
+
+- Braces on every `if` / `else`, including one-line guards.
+- Pick one meaning for `undefined` vs `null` and keep it. Do not use either as a stand-in for a named business state.
+- Name domain literals once (`const` / enum / const object). Do not scatter magic strings.
+
+```ts
+// Bad
+function getDiscount(user?: { plan?: { discount: number } }) {
+  if (!user) {
+    return null;
+  }
+  if (!user.plan) {
+    return null;
+  }
+  if (user.plan.discount === 0) {
+    return null;
+  }
+}
+
+// Good
+function getDiscount(user: { plan?: { discount: number } } | undefined): number {
+  if (user === undefined || user.plan === undefined) {
+    return 0;
+  }
+  return user.plan.discount;
+}
+```