@rmrdeveloper/sideroom-pi 8.7.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/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.7.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"
   }
 }