@rmrdeveloper/sideroom-pi 8.6.0 → 8.8.0

package/README.md

@@ -52,6 +52,7 @@ Sideroom answers each one with a small, opinionated surface:
 | 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 pre-edit gate + the on-demand `sideroom-guidelines` skill |
+| Invisible monorepo skills | `monorepo-skills` — trusted child folders join Pi's available skill list |
 | Vague plans | `sideroom-grill` — an interview that settles the words before the work |
 | Unapplied guidelines | `sideroom_rules` — mechanical checks that block or flag the lines you add |
 | Unclear answers | `sideroom_persona` — one voice: direct, plain, and free of jargon it invented |
@@ -86,6 +87,10 @@ wall of tool calls, it:
   blocked. The guides cover guard clauses, braced conditionals, fail-fast
   errors, focused units, and all 19 canonical rules without dumping them into
   the system prompt.
+- **Finds the skills below the working directory.** In a trusted monorepo, Pi
+  normally ignores project skills stored under child folders. Sideroom scans
+  three levels down, adds their `.pi/skills` and `.agents/skills`, and leaves
+  duplicate-name warnings to Pi.
 - **Cannot sneak sloppy lines past the gate.** Each write and edit is checked
   against the mechanical rules on the added lines only: braceless
   conditionals and swallowed errors block the mutation; vague names, stale
@@ -154,6 +159,19 @@ Each guide mirrors all 19 rules in the canonical seed with idiomatic examples.
 The seed, `assets/artifacts/GUIDELINES_TEMPLATE.md`, is never pasted into the
 system prompt.
 
+### Monorepo skills — child skills are still project skills
+
+Pi discovers `.pi/skills` only from its working directory and
+`.agents/skills` from that directory and its ancestors. `monorepo-skills`
+closes the downward gap: in a trusted project it scans at most three child
+levels, respects `.gitignore`, `.ignore`, and `.fdignore`, and contributes the
+same skill locations without writing project configuration. Skill bodies stay
+on demand; only names, descriptions, and locations enter the system prompt.
+
+Duplicate names keep Pi's precedence and diagnostics. Root and global skills
+load before extension paths, so use `pi config -l` to disable one that shadows
+a needed child-folder skill.
+
 ### Rules — enforcement, not advice
 
 The guidelines gate makes the agent read the rules; `sideroom_rules` makes it
@@ -272,6 +290,19 @@ languages use the shared table. Do not route around
 the gate through Bash or another file-mutation path. Before finishing, review
 the diff against the loaded guide and run the relevant project checks.
 
+### Monorepo-skills contract
+
+- Trigger: `resources_discover` after project trust resolves, in every mode.
+- Scope: `.pi/skills` and `.agents/skills` in child folders at most three
+  levels below Pi's working directory.
+- Traversal: ignore-aware, no directory symlinks, deterministic child-folder
+  order, `.pi/skills` before `.agents/skills` inside one folder.
+- Safety: untrusted projects and CLI `--no-skills`/`-ns` contribute no paths.
+- Collisions: Pi keeps the first name and reports skipped paths. Child-folder
+  skills cannot override root or user skills added earlier.
+- Prompt: one static, idempotent note prefers the skill whose location matches
+  the folder being edited.
+
 ### Rules contract
 
 - Trigger: every `write`/`edit` call, in every mode.
@@ -338,7 +369,9 @@ skills. If a third-party skill still wins, remove it from routing by adding
 `disable-model-invocation: true` to its frontmatter, or exclude its path with
 `-path` in `settings.skills`. A literal name collision keeps the first skill
 found: project `.pi/skills`, then project `.agents/skills`, then
-`~/.pi/agent/skills`, then `~/.agents/skills`, then packages.
+`~/.pi/agent/skills`, then `~/.agents/skills`, then packages. Child-folder
+paths contributed by `monorepo-skills` come later and cannot override any of
+them.
 
 ## Documentation
 

package/extensions/ask/index.ts

@@ -15,8 +15,8 @@ export const ASK_PROMPT_SNIPPET =
   'Ask the user one or more questions with a recommended option, in their language.';
 
 export const ASK_PROMPT_GUIDELINES = [
-  'When a non-trivial request is not yet a settled spec, follow the sideroom-grill skill before implementing; it owns the interview and drives sideroom_ask rounds. One sideroom_ask call is one batch; call it again for another round.',
-  'A decision the repository already settles consistently is a project fact: read the code and reuse it. A decision that materially affects architecture, dependencies, cost, security, operations, persistence, public contracts, or future change difficulty is an architectural decision: expose it through sideroom_ask before committing, with the practical consequences of each alternative and one recommendation that carries a one-line justification, never a list of technology names. If the repository shows two inconclusive patterns for the same kind of decision, name the inconsistency in the prompt. Everything else is a minor decision: take it yourself.',
+  'When a non-trivial request is not yet a settled spec, follow the sideroom-grill skill before implementing; it drives sideroom_ask rounds. One sideroom_ask call is one batch; call it again for another round.',
+  'A decision the repository already settles consistently is a project fact: read the code and reuse it. A decision that materially affects architecture, dependencies, cost, security, operations, persistence, public contracts, or future change difficulty is an architectural decision: never assume it; follow the sideroom-architecture skill and expose it through sideroom_ask before committing, with the practical consequences of each alternative and one recommendation carrying a one-line justification, never technology names. If the repository shows two inconclusive patterns for the same decision, name the inconsistency in the prompt. Everything else is a minor decision: take it yourself.',
   'Write sideroom_ask prompts, tab labels, option labels, and option descriptions in the language the user is speaking; keep ids and option values in English.',
   'sideroom_ask always adds Out of scope and a write-your-own answer; never send them yourself. A single-selection question needs recommendationIndex; a multiple-selection question needs recommendedIndices and never recommendationIndex.',
   'sideroom_ask only works in the interactive TUI; it errors in print, JSON, and RPC modes.',

package/extensions/monorepo-skills/flags.ts

@@ -0,0 +1,9 @@
+const END_OF_OPTIONS = '--';
+const NO_SKILLS_FLAGS = new Set(['--no-skills', '-ns']);
+
+export function areSkillsDisabled(argv: readonly string[]): boolean {
+  const endOfOptions = argv.indexOf(END_OF_OPTIONS);
+  const optionArguments =
+    endOfOptions === -1 ? argv : argv.slice(0, endOfOptions);
+  return optionArguments.some((argument) => NO_SKILLS_FLAGS.has(argument));
+}

package/extensions/monorepo-skills/index.ts

@@ -0,0 +1,36 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { areSkillsDisabled } from './flags.ts';
+import { appendMonorepoSkillsNote } from './prompt.ts';
+import { findMonorepoSkillPaths } from './scan.ts';
+
+// Pi loads extensions/*/index.ts through export default.
+export default function registerMonorepoSkills(pi: ExtensionAPI): void {
+  let hasMonorepoSkills = false;
+
+  pi.on('resources_discover', (event, ctx) => {
+    hasMonorepoSkills = false;
+    if (!ctx.isProjectTrusted() || areSkillsDisabled(process.argv)) {
+      return;
+    }
+
+    const skillPaths = findMonorepoSkillPaths(event.cwd);
+    if (skillPaths.length === 0) {
+      return;
+    }
+
+    hasMonorepoSkills = true;
+    return { skillPaths };
+  });
+
+  pi.on('before_agent_start', (event) => {
+    if (!hasMonorepoSkills) {
+      return;
+    }
+
+    const systemPrompt = appendMonorepoSkillsNote(event.systemPrompt);
+    if (systemPrompt === event.systemPrompt) {
+      return;
+    }
+    return { systemPrompt };
+  });
+}

package/extensions/monorepo-skills/prompt.ts

@@ -0,0 +1,14 @@
+export const MONOREPO_SKILLS_NOTE_HEADING = 'Sideroom monorepo skills:';
+
+export const MONOREPO_SKILLS_NOTE = `${MONOREPO_SKILLS_NOTE_HEADING}
+Some available skills come from child folders of this repository. When skills cover the same work, prefer the skill whose location is inside the folder you are editing.`;
+
+export function appendMonorepoSkillsNote(systemPrompt: string): string {
+  if (systemPrompt.includes(MONOREPO_SKILLS_NOTE_HEADING)) {
+    return systemPrompt;
+  }
+  if (systemPrompt.length === 0) {
+    return MONOREPO_SKILLS_NOTE;
+  }
+  return `${systemPrompt}\n\n${MONOREPO_SKILLS_NOTE}`;
+}

package/extensions/monorepo-skills/scan.ts

@@ -0,0 +1,225 @@
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import ignore from 'ignore';
+
+const MAX_CHILD_DEPTH = 3;
+const IGNORE_FILE_NAMES = ['.gitignore', '.ignore', '.fdignore'] as const;
+const NODE_MODULES_DIRECTORY = 'node_modules';
+const PI_DIRECTORY = '.pi';
+const AGENTS_DIRECTORY = '.agents';
+const SKILLS_DIRECTORY = 'skills';
+const SKILL_FILE_NAME = 'SKILL.md';
+const MARKDOWN_EXTENSION = '.md';
+
+export function findMonorepoSkillPaths(cwd: string): string[] {
+  const rootDirectory = resolve(cwd);
+  const childDirectories = collectChildDirectories(
+    rootDirectory,
+    rootDirectory,
+    0,
+    [],
+  );
+  childDirectories.sort((left, right) =>
+    compareText(relative(rootDirectory, left), relative(rootDirectory, right)),
+  );
+
+  const skillPaths: string[] = [];
+  for (const childDirectory of childDirectories) {
+    const piSkillsDirectory = join(
+      childDirectory,
+      PI_DIRECTORY,
+      SKILLS_DIRECTORY,
+    );
+    if (isDirectory(piSkillsDirectory)) {
+      skillPaths.push(piSkillsDirectory);
+    }
+
+    const agentsSkillsDirectory = join(
+      childDirectory,
+      AGENTS_DIRECTORY,
+      SKILLS_DIRECTORY,
+    );
+    if (isDirectory(agentsSkillsDirectory)) {
+      skillPaths.push(...collectAgentsSkillPaths(agentsSkillsDirectory));
+    }
+  }
+  return skillPaths;
+}
+
+function collectChildDirectories(
+  directory: string,
+  rootDirectory: string,
+  depth: number,
+  inheritedIgnorePatterns: readonly string[],
+): string[] {
+  if (depth >= MAX_CHILD_DEPTH) {
+    return [];
+  }
+
+  const ignorePatterns = [
+    ...inheritedIgnorePatterns,
+    ...readIgnoreRules(directory, rootDirectory),
+  ];
+  const ignoreMatcher = ignore().add(ignorePatterns);
+  const childDirectories: string[] = [];
+  for (const entry of readDirectoryEntries(directory)) {
+    if (!entry.isDirectory() || isTraversalDirectory(entry.name)) {
+      continue;
+    }
+
+    const childDirectory = join(directory, entry.name);
+    const relativeChild = toPosixPath(relative(rootDirectory, childDirectory));
+    if (ignoreMatcher.ignores(`${relativeChild}/`)) {
+      continue;
+    }
+
+    childDirectories.push(
+      childDirectory,
+      ...collectChildDirectories(
+        childDirectory,
+        rootDirectory,
+        depth + 1,
+        ignorePatterns,
+      ),
+    );
+  }
+  return childDirectories;
+}
+
+function collectAgentsSkillPaths(skillsDirectory: string): string[] {
+  return collectAgentsSkillPathsFromDirectory(
+    skillsDirectory,
+    skillsDirectory,
+    [],
+  );
+}
+
+function collectAgentsSkillPathsFromDirectory(
+  directory: string,
+  rootDirectory: string,
+  inheritedIgnorePatterns: readonly string[],
+): string[] {
+  const ignorePatterns = [
+    ...inheritedIgnorePatterns,
+    ...readIgnoreRules(directory, rootDirectory),
+  ];
+  const ignoreMatcher = ignore().add(ignorePatterns);
+  const entries = readDirectoryEntries(directory);
+  const declaredSkill = entries.find((entry) => {
+    if (entry.name !== SKILL_FILE_NAME || !entry.isFile()) {
+      return false;
+    }
+    const relativeSkill = toPosixPath(
+      relative(rootDirectory, join(directory, entry.name)),
+    );
+    return !ignoreMatcher.ignores(relativeSkill);
+  });
+  if (declaredSkill) {
+    return [join(directory, declaredSkill.name)];
+  }
+
+  const skillPaths: string[] = [];
+  for (const entry of entries) {
+    if (isTraversalDirectory(entry.name)) {
+      continue;
+    }
+
+    const entryPath = join(directory, entry.name);
+    const relativeEntry = toPosixPath(relative(rootDirectory, entryPath));
+    if (entry.isFile()) {
+      if (
+        directory !== rootDirectory &&
+        entry.name.endsWith(MARKDOWN_EXTENSION) &&
+        !ignoreMatcher.ignores(relativeEntry)
+      ) {
+        skillPaths.push(entryPath);
+      }
+      continue;
+    }
+    if (!entry.isDirectory() || ignoreMatcher.ignores(`${relativeEntry}/`)) {
+      continue;
+    }
+    skillPaths.push(
+      ...collectAgentsSkillPathsFromDirectory(
+        entryPath,
+        rootDirectory,
+        ignorePatterns,
+      ),
+    );
+  }
+  return skillPaths;
+}
+
+function readIgnoreRules(directory: string, rootDirectory: string): string[] {
+  const relativeDirectory = relative(rootDirectory, directory);
+  const prefix = relativeDirectory ? `${toPosixPath(relativeDirectory)}/` : '';
+  const ignorePatterns: string[] = [];
+
+  for (const fileName of IGNORE_FILE_NAMES) {
+    const ignorePath = join(directory, fileName);
+    if (!existsSync(ignorePath)) {
+      continue;
+    }
+
+    ignorePatterns.push(
+      ...readFileSync(ignorePath, 'utf8')
+        .split(/\r?\n/)
+        .map((line) => prefixIgnorePattern(line, prefix))
+        .filter((pattern): pattern is string => pattern !== undefined),
+    );
+  }
+  return ignorePatterns;
+}
+
+function prefixIgnorePattern(line: string, prefix: string): string | undefined {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) {
+    return undefined;
+  }
+  if (trimmed.startsWith('#') && !trimmed.startsWith('\\#')) {
+    return undefined;
+  }
+
+  let pattern = line;
+  let negated = false;
+  if (pattern.startsWith('!')) {
+    negated = true;
+    pattern = pattern.slice(1);
+  } else if (pattern.startsWith('\\!')) {
+    pattern = pattern.slice(1);
+  }
+  if (pattern.startsWith('/')) {
+    pattern = pattern.slice(1);
+  }
+
+  const prefixed = prefix ? `${prefix}${pattern}` : pattern;
+  return negated ? `!${prefixed}` : prefixed;
+}
+
+function readDirectoryEntries(directory: string) {
+  return readdirSync(directory, { withFileTypes: true }).sort((left, right) =>
+    compareText(left.name, right.name),
+  );
+}
+
+function isDirectory(path: string): boolean {
+  return existsSync(path) && lstatSync(path).isDirectory();
+}
+
+function isTraversalDirectory(name: string): boolean {
+  return name.startsWith('.') || name === NODE_MODULES_DIRECTORY;
+}
+
+function toPosixPath(path: string): string {
+  return path.split(sep).join('/');
+}
+
+function compareText(left: string, right: string): number {
+  if (left < right) {
+    return -1;
+  }
+  if (left > right) {
+    return 1;
+  }
+  return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rmrdeveloper/sideroom-pi",
-  "version": "8.6.0",
+  "version": "8.8.0",
   "description": "Pi coding-agent package that asks clarifying questions, shows a live todo board, enforces coding guidelines, and will not call it done while your checks are red.",
   "type": "module",
   "files": [
@@ -94,5 +94,8 @@
     "@types/node": "^22.20.1",
     "typebox": "1.3.7",
     "typescript": "^5.6.0"
+  },
+  "dependencies": {
+    "ignore": "7.0.5"
   }
 }

package/skills/sideroom-architecture/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: sideroom-architecture
+description: "Surface the architectural decisions a change forces so they are asked, not silently assumed. Use when a feature or change touches module boundaries, data ownership, integration contracts, failure behavior, quality attributes, operations, cost, lock-in, or reversibility, or when the user says the architecture is not settled. Do not use for a trivial or reversible change, a pure glossary lookup, or an already-closed spec."
+license: MIT
+metadata:
+  author: RMRdeveloper
+  version: "1.0"
+---
+
+# Sideroom architecture
+
+## Purpose
+
+An LLM's default failure is to assume the architecture and start typing. This
+skill forces the opposite: name the architectural decisions a change forces and
+ask the ones that matter, instead of picking them silently. It does not turn
+every change into an interrogation.
+
+## Activation Contract
+
+Load this skill when a change is about to commit an architectural decision:
+something that materially affects module boundaries, data ownership,
+integration contracts, failure behavior, quality attributes (latency,
+throughput, availability), operations, cost, lock-in, or the difficulty of
+changing course later. It runs under `sideroom-grill` for the architectural
+part of an interview, and on its own when only the architecture is open.
+
+Do not load it for a minor decision (reversible, no boundary or contract
+impact), or for a word conflict — that is `sideroom-domain-modeling`.
+
+## Hard Rules
+
+- Assume nothing architectural. When a change forces an architectural decision
+  the code does not already settle, expose it through `sideroom_ask` before
+  writing the code. Silent selection of an architectural default is the failure
+  this skill exists to prevent.
+- Pick the dimensions this decision actually touches; do not march the whole
+  catalog. Two sharp questions beat nine shallow ones. A dimension the change
+  does not touch is not asked.
+- Read the code first. A decision the repository already settles consistently
+  is a project fact: reuse it, never ask it. When the repository shows two
+  inconclusive patterns for the same kind of decision, name that inconsistency
+  in the prompt instead of picking one.
+- Quantify or decline. An architectural dimension does not close without a
+  number, a range, or an explicit `Out of scope` from the user. A decision
+  without a figure is a preference in disguise.
+- Every option of an architectural question carries a `description`: its
+  practical consequence, its cost, and the obligation it imposes. The label
+  names the choice; the description carries the trade-off. Never a one-word
+  technology label.
+- Present the decision as the current situation, the alternatives by their
+  practical consequences, and one recommendation with a one-line justification.
+  Never reduce it to technology names.
+- One open architectural dimension blocks implementation. `Out of scope` closes
+  a thread, is recorded, and is not re-asked.
+
+## Dimension catalog
+
+Reference, not a checklist. Pick only what the change touches; force a number or
+an explicit `Out of scope` on each one you pick.
+
+| Dimension | The question it forces |
+| --- | --- |
+| Boundaries | Which modules are in, which are out, which dependency direction is forbidden |
+| Data | What is the source of truth, who owns it, how the schema evolves and migrates |
+| Integration | Synchronous or asynchronous, backward compatibility, version window |
+| Quality attributes | Expected latency and volume, availability target — in figures |
+| Failure | What degrades, what retries, what must be idempotent |
+| Operations | How it deploys, how it rolls back, which signal warns it is going wrong |
+| Cost and lock-in | Operating cost, the cost of leaving the provider or dependency |
+| Ownership | Who maintains it, who responds when it breaks |
+| Reversibility | What reopens the decision, and how expensive undoing it is |
+
+## Execution Steps
+
+1. Read the code around the change. Settle every project fact from the
+   codebase, and note any inconsistent pattern to name in a prompt.
+2. List the architectural decisions the change forces. Drop the ones the code
+   already settles.
+3. For each remaining decision, pick the dimensions it touches and run one
+   `sideroom_ask` round: situation, alternatives by consequence, one
+   recommendation, each option with a `description`. Force a number or an
+   explicit `Out of scope`.
+4. Repeat rounds until no architectural dimension is open. Do not implement
+   with one open.
+5. Record an accepted decision as an ADR under `docs/adr/` only when it clears
+   the three `sideroom-domain-modeling` gates: hard to reverse, surprising
+   without context, the result of a real trade-off. The ADR names the rejected
+   alternatives and what reopens the decision.
+
+## Output Contract
+
+Before the first round: a one-line statement of what is built, what it touches,
+what is out. After the rounds: the architectural decisions closed with their
+figures, the dimensions marked out of scope, and any ADR written with its
+rejected alternatives and its revision trigger. No architectural default
+reaches the code without having been asked or read from the repository.
+
+## References
+
+- Driven by `sideroom-grill` for the architectural part of an interview; that
+  skill owns the interview, this one owns the architectural interrogation.
+- Hands qualifying decisions to `sideroom-domain-modeling` for the ADR
+  three-gate offer and records shared vocabulary through it.