@cratis/pi 7.1.5 → 7.2.0

package/README.md

@@ -9,8 +9,8 @@ pi install -l npm:@cratis/pi
 
 The package reads the repository's `.cratis/ai.json`, resolves its profiles and
 languages through the packaged profile catalog, and contributes only the matching
-skills. It also loads packaged rules, prompts, agents, the subagent tool, and
-Cratis quality hooks. When no `.cratis/ai.json` exists, it exposes the complete
+skills. It also loads packaged rules, path guidance, prompts, agents, the
+subagent tool, and Cratis quality hooks. When no `.cratis/ai.json` exists, it exposes the complete
 packaged skill set. It therefore gives Pi the complete single-harness Cratis
 experience without requiring the Cratis CLI.
 
@@ -24,7 +24,48 @@ The managed CLI path remains the choice when one repository must configure and
 synchronize several harnesses. It writes the resolved corpus to `.cratis/ai`,
 creates every harness integration, and records hashes for safe update and
 uninstall. That managed setup loads rules through its own `.pi/extensions/cratis-rules`
-extension and does not require this package. If both paths are present, the package
+and `.pi/extensions/cratis-path-guidance` extensions and does not require this package. If both paths are present, the package
 yields to the managed installation to avoid duplicate resources and hooks. The Pi
 package manages only Pi; it neither configures other harnesses nor owns a local
 managed corpus.
+
+## Path guidance and subagents
+
+The packaged `cratis-path-guidance` extension attaches a path-scoped rule to the
+tool result the first time a matching file is touched, and after a successful
+`write` or `edit` adds one advisory line naming every skill whose `SKILL.md`
+`cratis-hint-paths` frontmatter matches the file. (The key is Cratis-specific
+because Claude Code gives a plain `paths` key its own meaning.) A skill is hinted at
+most once per session and not when it is already in context: read (a shell command
+counts only when `cat`, `sed`, `head`, `tail`, `less`, `bat`, `rg` or `grep` opens
+its `SKILL.md` or a file under `references/`), preloaded by pi-subagents, or
+expanded by `/skill:name`. A pi-subagents header without the skill's text (its
+loader cannot read a symlinked `.pi/skills`) does not count as preloaded. The
+skills considered are the ones Pi loaded plus the skills the repository selected
+(`.cratis/ai.json`), so a session whose Pi skill list holds only personal skills,
+or none (for example `skills: false`), still gets hints; an unselected skill is
+never hinted, and none is added if the selection cannot be resolved. Rules follow
+the same language and documentation selection as the system prompt. Nothing is
+blocked and the system prompt is untouched. The system prompt carries only the
+universal rules, so path-scoped rules are not delivered twice. The extension works
+in sessions without a UI. It stands down when a managed installation
+(`.cratis/ai.manifest.json`) already delivers path guidance: through its own
+`.pi/extensions/cratis-path-guidance`, or through any `.pi/extensions/cratis-rules`
+that is not the current universal-only version, since every earlier version
+delivers path-scoped rules itself. A `cratis-rules` that cannot be recognised
+counts as one that delivers them. In such an older managed installation, a subagent
+that loads only the allowlisted extensions below gets no path guidance until
+`cratis ai update` installs the managed `cratis-path-guidance`.
+
+The universal rules add about 26k tokens to every session. A pi-subagents agent
+(`@tintinweb/pi-subagents`) with an `extensions:` allowlist loads only the
+extensions it names, so it gets none of this package by default. Name the two
+cheap extensions to give it path guidance and the write and store guards without
+the universal rules:
+
+```yaml
+extensions: cratis-path-guidance, cratis-hooks
+```
+
+The `subagent` tool of this package starts a full `pi` process and loads every
+extension.

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/LoadedSkill.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The part of a Pi skill (`event.systemPromptOptions.skills`) this extension reads. */
+export interface LoadedSkill {
+    name: string;
+    filePath: string;
+    baseDir?: string;
+}

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/SkillMatch.ts

@@ -0,0 +1,10 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { SkillTrigger } from './SkillTrigger.ts';
+
+/** A skill whose trigger matched a path, with the glob that matched. */
+export interface SkillMatch {
+    skill: SkillTrigger;
+    glob: string;
+}

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/SkillTrigger.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** A skill available to the session together with the path globs its `SKILL.md` declares as triggers. */
+export interface SkillTrigger {
+    name: string;
+    /** Absolute path of the skill's `SKILL.md`. */
+    filePath: string;
+    /** Directory holding `SKILL.md` and the skill's references. */
+    baseDir: string;
+    /** The `cratis-hint-paths` frontmatter of the skill. Empty when the skill declares no trigger. */
+    globs: string[];
+}

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/ToolName.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The Pi tools whose results carry a file path this extension reacts to. */
+export enum ToolName {
+    Read = 'read',
+    Write = 'write',
+    Edit = 'edit',
+    Bash = 'bash',
+    PowerShell = 'powershell',
+}

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/index.ts

@@ -0,0 +1,166 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { ManagedRule } from '../shared/ManagedRule.ts';
+import { rulesForPath } from '../shared/rules.ts';
+import type { LoadedSkill } from './LoadedSkill.ts';
+import type { SkillMatch } from './SkillMatch.ts';
+import type { SkillTrigger } from './SkillTrigger.ts';
+import { skillsRead } from './skillReads.ts';
+import { skillsForPath, skillTriggers } from './skills.ts';
+import { standsDown } from './standDown.ts';
+import { ToolName } from './ToolName.ts';
+import { touchedPaths } from './touchedPaths.ts';
+
+const extensionDirectory = dirname(fileURLToPath(import.meta.url));
+const isPackagedExtension = extensionDirectory.includes(`${sep}package${sep}corpus${sep}`);
+
+function repositoryRelative(cwd: string, path: string): string | undefined {
+    const relativePath = relative(cwd, resolve(cwd, path));
+    return !relativePath || relativePath.startsWith('..') || isAbsolute(relativePath) ? undefined : relativePath.split(sep).join('/');
+}
+
+function displayPath(cwd: string, path: string): string {
+    return repositoryRelative(cwd, path) ?? path;
+}
+
+/** One line for everything a write matched, however many skills, so overlapping triggers cost one line and not several. */
+function hintLine(cwd: string, files: string[], matches: SkillMatch[]): string {
+    const skills = matches.map(match => `\`${match.skill.name}\` (matched \`${match.glob}\`)`);
+    const named = skills.length === 1 ? `Skill ${skills[0]} covers` : `Skills ${skills.slice(0, -1).join(', ')} and ${skills[skills.length - 1]} cover`;
+    const documents = matches.map(match => displayPath(cwd, match.skill.filePath));
+    const read = documents.length === 1 ? documents[0] : `${documents.slice(0, -1).join(', ')} and ${documents[documents.length - 1]}`;
+    return `[cratis-path-guidance] ${named} ${files.join(', ')}; read ${read} before continuing.`;
+}
+
+/**
+ * pi-subagents writes `# Preloaded Skill: <name>` for every name in `skills:` and then the skill's text, or a
+ * placeholder when it could not load it: `(Skill "<name>" not found in ...)` or `(Skill "<name>" skipped: ...)`.
+ * It cannot load a skill from a symlinked skills root, which is how a managed installation exposes
+ * `.pi/skills` and `.agents/skills`. Only a header followed by real content puts the skill in context.
+ */
+const placeholderBody = /^\(Skill "[^"]*" (?:not found|skipped)\b/;
+
+/** The skills pi-subagents preloaded into the system prompt (`skills: a, b`) whose full text is already in context. */
+function preloadedSkillNames(systemPrompt: unknown): Set<string> {
+    const names = new Set<string>();
+    if (typeof systemPrompt !== 'string') return names;
+    for (const match of systemPrompt.matchAll(/^# Preloaded Skill: (\S+)[ \t]*\r?\n/gm)) {
+        const body = systemPrompt.slice(match.index + match[0].length).split(/^# Preloaded Skill: /m)[0].trim();
+        if (body.length > 0 && !placeholderBody.test(body)) names.add(match[1]);
+    }
+    return names;
+}
+
+/** The skills a `/skill:name` command expanded into the user message, which arrive without a `read` call. */
+function expandedSkillNames(prompt: unknown): string[] {
+    return typeof prompt === 'string' ? [...prompt.matchAll(/<skill name="([^"]+)"/g)].map(match => match[1]) : [];
+}
+
+/**
+ * Delivers the corpus guidance that belongs to a file at the moment the file is touched, so it works in every
+ * Pi process, including a subagent, without the universal rules `cratis-rules` puts in every system prompt.
+ *
+ * Path-scoped rules are attached to the tool result the first time a matching file is touched in the session,
+ * exactly as they were when `cratis-rules` delivered them. On a successful `write` or `edit`, one advisory line
+ * names every skill whose `cratis-hint-paths` frontmatter matches the file and where its `SKILL.md` is. A skill
+ * is not hinted when it is already in context: read in the session, preloaded by pi-subagents
+ * (`# Preloaded Skill: <name>` followed by its text in the system prompt), or expanded by `/skill:<name>`. Hints are advisory only:
+ * nothing is blocked and the system prompt is never touched.
+ *
+ * Delivery happens on `tool_result`, so guidance arrives after the call that first touched the file.
+ * `ToolCallEventResult` carries only `block`/`reason`/`terminate`, so there is no supported way to add
+ * context before a tool runs. In practice a file is read before it is edited, and reads through both the read
+ * tool and bash are covered; a file created blind by `write` is the residual case, and it receives the
+ * guidance with that result.
+ *
+ * Delivered guidance lives in the conversation rather than the system prompt, so anything that rewrites or
+ * replaces the conversation can remove it. The delivery record is therefore reset whenever that happens, and the
+ * guidance is delivered again the next time one of its files is touched.
+ */
+export default function (pi: ExtensionAPI): void {
+    if (standsDown(isPackagedExtension, process.cwd())) return;
+
+    const deliveredRules = new Set<string>();
+    const hintedSkills = new Set<string>();
+    const readSkills = new Set<string>();
+    // Preloaded skills live in the system prompt, which compaction leaves alone, so this is replaced at each
+    // agent start rather than reset with the conversation.
+    let preloadedSkills = new Set<string>();
+    let loadedSkills: LoadedSkill[] | undefined;
+    let loadedKey: string | undefined;
+    let triggers: SkillTrigger[] | undefined;
+
+    const availableTriggers = (cwd: string): SkillTrigger[] => triggers ??= skillTriggers(loadedSkills, cwd);
+
+    // Compaction summarizes the conversation, which can drop an injected rule or hint while leaving the
+    // delivery record claiming it is present; a switch replaces the conversation outright.
+    const reset = () => {
+        deliveredRules.clear();
+        hintedSkills.clear();
+        readSkills.clear();
+        triggers = undefined;
+    };
+    pi.on('session_start', reset);
+    pi.on('session_compact', reset);
+    pi.on('session_before_switch', reset);
+
+    // Only observes which skills are in context for this session; the system prompt is never changed.
+    pi.on('before_agent_start', event => {
+        const observed = event as { systemPrompt?: unknown; prompt?: unknown; systemPromptOptions?: { skills?: LoadedSkill[] } };
+        preloadedSkills = preloadedSkillNames(observed.systemPrompt);
+        expandedSkillNames(observed.prompt).forEach(name => readSkills.add(name));
+        const skills = observed.systemPromptOptions?.skills;
+        const key = skills?.map(skill => `${skill.name}\t${skill.filePath}`).join('\n');
+        if (key !== loadedKey) triggers = undefined;
+        loadedSkills = skills;
+        loadedKey = key;
+        return undefined;
+    });
+
+    pi.on('tool_result', (event, context) => {
+        if (event.isError) return;
+        const cwd = context.cwd;
+        const toolName: string = event.toolName;
+        const input = event.input;
+
+        const reads = skillsRead(toolName, input, availableTriggers(cwd));
+        reads.forEach(skill => readSkills.add(skill.name));
+
+        const pendingRules: ManagedRule[] = [];
+        const matchedFiles: string[] = [];
+        const hintedFiles: string[] = [];
+        const pendingMatches: SkillMatch[] = [];
+        for (const path of touchedPaths(toolName, input, cwd)) {
+            const relativePath = repositoryRelative(cwd, path);
+            if (!relativePath) continue;
+            for (const rule of rulesForPath(cwd, relativePath)) {
+                if (deliveredRules.has(rule.name) || pendingRules.some(candidate => candidate.name === rule.name)) continue;
+                pendingRules.push(rule);
+                if (!matchedFiles.includes(relativePath)) matchedFiles.push(relativePath);
+            }
+            if (toolName !== ToolName.Write && toolName !== ToolName.Edit) continue;
+            for (const match of skillsForPath(availableTriggers(cwd), relativePath)) {
+                const name = match.skill.name;
+                if (hintedSkills.has(name) || readSkills.has(name) || preloadedSkills.has(name)) continue;
+                hintedSkills.add(name);
+                pendingMatches.push(match);
+                if (!hintedFiles.includes(relativePath)) hintedFiles.push(relativePath);
+            }
+        }
+        if (pendingRules.length === 0 && pendingMatches.length === 0) return;
+        pendingRules.forEach(rule => deliveredRules.add(rule.name));
+
+        const existing = Array.isArray(event.content) ? event.content : [];
+        const text = [
+            pendingRules.length === 0
+                ? undefined
+                : `\n\n[cratis-rules] Rules that apply to ${matchedFiles.join(', ')}:\n\n${pendingRules.map(rule => rule.content).join('\n\n')}`,
+            pendingMatches.length === 0 ? undefined : `\n\n${hintLine(cwd, hintedFiles, pendingMatches)}`,
+        ].filter(part => part !== undefined).join('');
+        return { content: [...existing, { type: 'text', text }] };
+    });
+}

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/skillReads.ts

@@ -0,0 +1,62 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { SkillTrigger } from './SkillTrigger.ts';
+import { ToolName } from './ToolName.ts';
+import { commandOf, isShellTool } from './touchedPaths.ts';
+
+/** Shell commands that put a file's content in front of the model. `ls`, `git diff` or `git add` do not. */
+const readers = new Set(['cat', 'sed', 'head', 'tail', 'less', 'bat', 'rg', 'grep']);
+
+/** `rtk` verbs that read: `rtk read`, `rtk cat`, and `rtk grep`/`rtk rg` on a file. */
+const rtkReaders = new Set(['read', ...readers]);
+
+function escapeRegExp(text: string): string {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Whether a path names a file inside the skill's directory. */
+function isInsideSkill(path: string, skill: SkillTrigger): boolean {
+    if (path.includes(`${skill.baseDir}/`)) return true;
+    return new RegExp(`(?:^|[/\\s'"=])skills/${escapeRegExp(skill.name)}/`).test(path.replaceAll('\\', '/'));
+}
+
+/** Whether text names the skill's `SKILL.md`, or a file under its `references/`. */
+function namesSkillDocument(text: string, skill: SkillTrigger): boolean {
+    const normalized = text.replaceAll('\\', '/');
+    if (normalized.includes(`${skill.baseDir}/SKILL.md`) || normalized.includes(`${skill.baseDir}/references/`)) return true;
+    return new RegExp(`(?:^|[/\\s'"=])skills/${escapeRegExp(skill.name)}/(?:SKILL\\.md|references/)`).test(normalized);
+}
+
+/**
+ * The commands of a shell line that read a file. The line is split at `&&`, `||`, `|`, `;` and newlines, and a
+ * command counts when its verb (after an optional `rtk` or `rtk proxy`) is a reader. An `echo`, a commit message
+ * or `git diff` that merely mentions a path is not a read.
+ */
+function readerCommands(command: string): string[] {
+    return command.split(/\s*(?:&&|\|\||\||;(?=\s|$)|\n)\s*/).filter(segment => {
+        const words = segment.trim().split(/\s+/);
+        if (words[0] !== 'rtk') return readers.has(words[0]);
+        const verb = words[1] === 'proxy' ? words[2] : words[1];
+        return words[1] === 'proxy' ? readers.has(verb) : rtkReaders.has(verb);
+    });
+}
+
+/**
+ * The skills a successful tool call read: the `read` tool on any file under `skills/<name>/`, or a shell reader
+ * (`cat`, `sed`, `head`, `tail`, `less`, `bat`, `rg`, `grep`, `rtk read`) on that skill's `SKILL.md` or a file
+ * under its `references/`. A model that opened either already has the skill's guidance. Listing the directory,
+ * or a `git` command that names the path, gives it nothing and is not a read.
+ */
+export function skillsRead(toolName: string, input: unknown, skills: SkillTrigger[]): SkillTrigger[] {
+    if (toolName === ToolName.Read) {
+        const candidate = input as { path?: unknown; file_path?: unknown } | undefined;
+        const value = candidate?.path ?? candidate?.file_path;
+        return typeof value === 'string' ? skills.filter(skill => isInsideSkill(value, skill)) : [];
+    }
+    if (!isShellTool(toolName)) return [];
+    const command = commandOf(input);
+    if (command === undefined) return [];
+    const commands = readerCommands(command);
+    return skills.filter(skill => commands.some(segment => namesSkillDocument(segment, skill)));
+}

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/skills.ts

@@ -0,0 +1,72 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { corpusRoot } from '../shared/corpusRoot.ts';
+import { frontmatter } from '../shared/frontmatter.ts';
+import { globToRegExp } from '../shared/globs.ts';
+import { skillTriggerKey } from '../shared/skillFrontmatter.ts';
+import { selectedSkillNames } from '../shared/skillSelection.ts';
+import type { LoadedSkill } from './LoadedSkill.ts';
+import type { SkillMatch } from './SkillMatch.ts';
+import type { SkillTrigger } from './SkillTrigger.ts';
+
+function skillAt(root: string, name: string): LoadedSkill[] {
+    const filePath = join(root, name, 'SKILL.md');
+    return existsSync(filePath) ? [{ name, filePath, baseDir: join(root, name) }] : [];
+}
+
+/**
+ * The skills the repository selected, whether or not Pi loaded them into the session. A managed installation resolves
+ * them into `.cratis/ai/skills`. Without one, the packaged corpus holds every catalog skill, so the selection
+ * comes from `.cratis/ai.json` and the profile catalog; when that cannot be resolved nothing is hinted.
+ */
+function repositorySkills(cwd: string): LoadedSkill[] {
+    const managedRoot = join(cwd, '.cratis', 'ai', 'skills');
+    if (existsSync(managedRoot)) {
+        return readdirSync(managedRoot, { withFileTypes: true })
+            .filter(entry => entry.isDirectory())
+            .flatMap(entry => skillAt(managedRoot, entry.name));
+    }
+    const packagedRoot = join(corpusRoot, 'skills');
+    return (selectedSkillNames(cwd) ?? []).flatMap(name => skillAt(packagedRoot, name));
+}
+
+function triggerGlobs(filePath: string): string[] {
+    try {
+        return frontmatter(readFileSync(filePath, 'utf8')).get(skillTriggerKey) ?? [];
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * The skills available to a session with their trigger globs: the skills Pi loaded for the session
+ * (`systemPromptOptions.skills`) together with the repository's selected skills, deduplicated by name with the
+ * loaded one winning. The union matters because Pi's list says nothing about whether the Cratis skills are in it:
+ * it can be empty (a pi-subagents agent with `skills: false`, the usual setup for cheap workers), or non-empty
+ * with only personal skills (an agent with `skills: true` whose `extensions:` allowlist leaves `@cratis/pi`, and
+ * so its skill paths, out). The selected skills' `SKILL.md` can still be read by path, which is what the hint asks
+ * for; a corpus skill the repository did not select is never added. Skills without a `cratis-hint-paths` trigger
+ * are left out.
+ */
+export function skillTriggers(loaded: LoadedSkill[] | undefined, cwd: string): SkillTrigger[] {
+    const loadedNames = new Set((loaded ?? []).map(skill => skill.name));
+    return [...(loaded ?? []), ...repositorySkills(cwd).filter(skill => !loadedNames.has(skill.name))]
+        .map(skill => ({
+            name: skill.name,
+            filePath: skill.filePath,
+            baseDir: skill.baseDir ?? dirname(skill.filePath),
+            globs: triggerGlobs(skill.filePath),
+        }))
+        .filter(skill => skill.globs.length > 0);
+}
+
+/** The skills whose trigger matches a repository-relative path, each with the first glob that matched. */
+export function skillsForPath(triggers: SkillTrigger[], relativePath: string): SkillMatch[] {
+    return triggers.flatMap(skill => {
+        const glob = skill.globs.find(candidate => globToRegExp(candidate).test(relativePath));
+        return glob === undefined ? [] : [{ skill, glob }];
+    });
+}

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/standDown.ts

@@ -0,0 +1,48 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Whether a managed `cratis-rules` delivers path-scoped rules itself, which is every generation but the current one:
+ *
+ * - `6b0bb54`, `5b048c6`: `before_agent_start` concatenates every rule into the system prompt;
+ * - `aca9c6b`, `59362cf`, `1937b06`, `eec744a`: universal rules in the system prompt, path-scoped rules on
+ *   `tool_result`;
+ * - current: universal rules only, taken from `../shared/rules.ts`, with no `tool_result` handler.
+ *
+ * Only a file that is recognisably the current one, importing the shared rules and having no `tool_result`
+ * handler, is trusted not to deliver path rules; anything else, including a file that cannot be read, is assumed
+ * to. Standing down on a guess costs allowlisted subagents their path guidance until `cratis ai update`, which
+ * is cheaper than duplicating every path-scoped rule in every full session.
+ */
+function managedRulesDeliverPaths(cwd: string): boolean {
+    const path = join(cwd, '.pi', 'extensions', 'cratis-rules', 'index.ts');
+    if (!existsSync(path)) return false;
+    try {
+        const content = readFileSync(path, 'utf8');
+        return !content.includes("'../shared/rules.ts'") || content.includes('tool_result');
+    } catch {
+        return true;
+    }
+}
+
+/**
+ * A managed installation (`.cratis/ai.manifest.json`) loads its own extensions from `.pi/extensions`. The copy
+ * shipped in `@cratis/pi` stands down when that installation already delivers path guidance, so a rule or hint
+ * is never delivered twice, whichever versions are mixed:
+ *
+ * - the managed `cratis-path-guidance` exists: it delivers rules and hints;
+ * - an older managed `cratis-rules` exists, which delivers path-scoped rules itself, in the system prompt or on
+ *   `tool_result`: the packaged copy would repeat every rule, so it yields until `cratis ai update` installs the
+ *   managed copy;
+ * - a current managed `cratis-rules` that only injects universal rules, or no managed Pi extensions at all:
+ *   nothing else delivers path guidance, so the packaged copy stays active.
+ *
+ * The managed copy never stands down.
+ */
+export function standsDown(packaged: boolean, cwd: string): boolean {
+    if (!packaged || !existsSync(join(cwd, '.cratis', 'ai.manifest.json'))) return false;
+    return existsSync(join(cwd, '.pi', 'extensions', 'cratis-path-guidance', 'index.ts')) || managedRulesDeliverPaths(cwd);
+}

package/package/corpus/harnesses/pi/extensions/cratis-path-guidance/touchedPaths.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { ToolName } from './ToolName.ts';
+
+/** Upper bound on files considered from one bash command, so a wide command cannot deliver the corpus. */
+const maxPathsPerCommand = 10;
+
+export function isShellTool(toolName: string): boolean {
+    return toolName === ToolName.Bash || toolName === ToolName.PowerShell;
+}
+
+export function commandOf(input: unknown): string | undefined {
+    const command = (input as { command?: unknown } | undefined)?.command;
+    return typeof command === 'string' ? command : undefined;
+}
+
+/**
+ * Extracts file paths a bash command refers to. `rtk.md` tells agents to run `rtk read`, `rtk grep`
+ * and `rtk find` from the terminal for bulk reads, so file access frequently arrives as a bash
+ * command rather than the read tool; without this, a session that follows that rule would never
+ * receive a path-scoped rule. A token counts only when it resolves to a file that exists inside the
+ * working directory, which keeps a filename mentioned inside a commit message from matching.
+ */
+function pathsFromCommand(command: string, cwd: string): string[] {
+    const found: string[] = [];
+    for (const raw of command.split(/[\s;|&()<>]+/)) {
+        if (found.length >= maxPathsPerCommand) break;
+        const token = raw.replace(/^['"]+|['"]+$/g, '').replace(/[,:]+$/, '');
+        if (!token || token.startsWith('-') || !/[./]/.test(token)) continue;
+        try {
+            if (statSync(resolve(cwd, token)).isFile()) found.push(token);
+        } catch {
+            /* not a path we can see; ignore */
+        }
+    }
+    return found;
+}
+
+/** The file paths a tool call refers to, as the tool received them. */
+export function touchedPaths(toolName: string, input: unknown, cwd: string): string[] {
+    if (isShellTool(toolName)) {
+        const command = commandOf(input);
+        return command === undefined ? [] : pathsFromCommand(command, cwd);
+    }
+    if (toolName !== ToolName.Read && toolName !== ToolName.Write && toolName !== ToolName.Edit) return [];
+    const candidate = (input as { path?: unknown; file_path?: unknown } | undefined);
+    const value = candidate?.path ?? candidate?.file_path;
+    return typeof value === 'string' && value.length > 0 ? [value] : [];
+}

package/package/corpus/harnesses/pi/extensions/cratis-rules/index.ts

@@ -1,250 +1,19 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { dirname, join, relative, resolve, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-
-const corpusRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
-
-type AiConfiguration = { profiles?: string[] };
-
-export interface ManagedRule {
-    /** Path relative to the rules root, e.g. `code-quality-csharp.md` or `project/running-the-local-stack.md`. */
-    name: string;
-    /** Full file content, frontmatter included, exactly as the other harnesses receive it. */
-    content: string;
-    /** `application`, `framework`, or undefined when the rule is not profile-specific. */
-    profile?: string;
-    /** Globs from `applyTo` and `paths`. Empty means the rule applies to every file. */
-    globs: string[];
-}
-
-const universalGlobs = new Set(['**', '**/*', '*']);
-
-function unquote(value: string): string {
-    return value.trim().replace(/^["']|["']$/g, '');
-}
-
-/**
- * Reads the YAML-ish frontmatter the corpus uses: scalar `key: value` lines and `key:` followed by
- * `  - item` lines. Anything richer is not used by the rules and is deliberately not supported.
- */
-function frontmatter(content: string): Map<string, string[]> {
-    const fields = new Map<string, string[]>();
-    if (!content.startsWith('---\n')) return fields;
-    const end = content.indexOf('\n---\n', 4);
-    if (end < 0) return fields;
-    let current: string | undefined;
-    for (const line of content.slice(4, end).split('\n')) {
-        const item = /^\s+-\s+(.*)$/.exec(line);
-        if (item && current) {
-            fields.get(current)!.push(unquote(item[1]));
-            continue;
-        }
-        const scalar = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(line);
-        if (!scalar) continue;
-        current = scalar[1];
-        const value = unquote(scalar[2]);
-        fields.set(current, value ? value.split(',').map(unquote).filter(Boolean) : []);
-    }
-    return fields;
-}
-
-function escapeRegExp(text: string): string {
-    return text.replace(/[.+^$()|[\]\\]/g, '\\$&');
-}
-
-/** Converts the glob dialect used by `applyTo` (`**`, `*`, `?`, `{a,b}`) into an anchored RegExp. */
-export function globToRegExp(glob: string): RegExp {
-    let pattern = '';
-    for (let index = 0; index < glob.length; index++) {
-        const character = glob[index];
-        if (character === '*') {
-            if (glob[index + 1] === '*') {
-                if (glob[index + 2] === '/') {
-                    pattern += '(?:.*/)?';
-                    index += 2;
-                } else {
-                    pattern += '.*';
-                    index += 1;
-                }
-            } else {
-                pattern += '[^/]*';
-            }
-        } else if (character === '?') {
-            pattern += '[^/]';
-        } else if (character === '{') {
-            const close = glob.indexOf('}', index);
-            if (close > index) {
-                pattern += `(?:${glob.slice(index + 1, close).split(',').map(part => escapeRegExp(part.trim())).join('|')})`;
-                index = close;
-            } else {
-                pattern += '\\{';
-            }
-        } else {
-            pattern += escapeRegExp(character);
-        }
-    }
-    return new RegExp(`^${pattern}$`);
-}
-
-function rulesRoot(cwd: string): string {
-    const managedRoot = join(cwd, '.cratis', 'ai', 'rules');
-    return existsSync(managedRoot) ? managedRoot : join(corpusRoot, 'rules');
-}
-
-function configuration(cwd: string): AiConfiguration | undefined {
-    const path = join(cwd, '.cratis', 'ai.json');
-    if (!existsSync(path)) return undefined;
-    try {
-        return JSON.parse(readFileSync(path, 'utf8')) as AiConfiguration;
-    } catch {
-        return undefined;
-    }
-}
-
-/**
- * A profile-specific rule is kept only when the repository selects that profile. Repositories without
- * a `.cratis/ai.json` keep every rule, matching the `@cratis/pi` package.
- */
-function matchesProfile(rule: ManagedRule, selected: AiConfiguration | undefined): boolean {
-    if (!rule.profile || !selected) return true;
-    const profiles = selected.profiles ?? [];
-    if (rule.profile === 'application') return profiles.some(profile => profile.startsWith('cratis/application'));
-    if (rule.profile === 'framework') return profiles.some(profile => profile.startsWith('cratis/engineering'));
-    return true;
-}
-
-/** Loads every managed rule with its frontmatter interpreted, filtered to the repository's profiles. */
-export function managedRules(cwd: string): ManagedRule[] {
-    const root = rulesRoot(cwd);
-    const selected = configuration(cwd);
-    return readdirSync(root, { recursive: true, encoding: 'utf8' })
-        .filter((entry): entry is string => entry.endsWith('.md'))
-        .sort()
-        .map(entry => {
-            const content = readFileSync(join(root, entry), 'utf8');
-            const fields = frontmatter(content);
-            return {
-                name: entry.split(sep).join('/'),
-                content,
-                profile: fields.get('profile')?.[0],
-                globs: [...(fields.get('applyTo') ?? []), ...(fields.get('paths') ?? [])],
-            } satisfies ManagedRule;
-        })
-        .filter(rule => matchesProfile(rule, selected));
-}
-
-/** Rules that apply to every file. These belong in the system prompt. */
-export function universalRules(cwd: string): ManagedRule[] {
-    return managedRules(cwd).filter(rule => rule.globs.length === 0 || rule.globs.some(glob => universalGlobs.has(glob)));
-}
-
-/** Rules whose `applyTo`/`paths` match a repository-relative path. These are delivered when that file is touched. */
-export function rulesForPath(cwd: string, relativePath: string): ManagedRule[] {
-    const normalized = relativePath.split(sep).join('/');
-    return managedRules(cwd).filter(rule =>
-        rule.globs.length > 0 &&
-        !rule.globs.some(glob => universalGlobs.has(glob)) &&
-        rule.globs.some(glob => globToRegExp(glob).test(normalized)));
-}
-
-/** Upper bound on files considered from one bash command, so a wide command cannot deliver the corpus. */
-const maxPathsPerCommand = 10;
+import { universalRules } from '../shared/rules.ts';
 
 /**
- * Extracts file paths a bash command refers to. `rtk.md` tells agents to run `rtk read`, `rtk grep`
- * and `rtk find` from the terminal for bulk reads, so file access frequently arrives as a bash
- * command rather than the read tool; without this, a session that follows that rule would never
- * receive a path-scoped rule. A token counts only when it resolves to a file that exists inside the
- * working directory, which keeps a filename mentioned inside a commit message from matching.
- */
-function pathsFromCommand(command: string, cwd: string): string[] {
-    const found: string[] = [];
-    for (const raw of command.split(/[\s;|&()<>]+/)) {
-        if (found.length >= maxPathsPerCommand) break;
-        const token = raw.replace(/^['"]+|['"]+$/g, '').replace(/[,:]+$/, '');
-        if (!token || token.startsWith('-') || !/[./]/.test(token)) continue;
-        try {
-            if (statSync(resolve(cwd, token)).isFile()) found.push(token);
-        } catch {
-            /* not a path we can see; ignore */
-        }
-    }
-    return found;
-}
-
-function touchedPaths(toolName: string, input: unknown, cwd: string): string[] {
-    if (toolName === 'bash' || toolName === 'powershell') {
-        const command = (input as { command?: unknown } | undefined)?.command;
-        return typeof command === 'string' ? pathsFromCommand(command, cwd) : [];
-    }
-    if (toolName !== 'read' && toolName !== 'write' && toolName !== 'edit') return [];
-    const candidate = (input as { path?: unknown; file_path?: unknown } | undefined);
-    const value = candidate?.path ?? candidate?.file_path;
-    return typeof value === 'string' && value.length > 0 ? [value] : [];
-}
-
-/**
- * Gives Pi the same rule semantics as the other harnesses: universal rules in the system prompt, and
- * path-scoped rules attached the first time a matching file is touched in the session. Without this,
- * every rule was concatenated into every turn regardless of `applyTo`, `paths`, or `profile`.
- *
- * Delivery happens on `tool_result`, so a rule arrives after the call that first touched its file.
- * `ToolCallEventResult` carries only `block`/`reason`/`terminate`, so there is no supported way to add
- * context before a tool runs. In practice a file is read before it is edited, and reads through both
- * the read tool and bash are covered, so the rule is present before the edit; a file created blind by
- * `write` is the residual case, and it receives the rule with that result.
+ * Puts the universal rules in the system prompt, giving Pi the same rule semantics as the other harnesses.
+ * Rules scoped by `applyTo`, `paths` or `profile` are not concatenated into every turn; the
+ * `cratis-path-guidance` extension attaches path-scoped rules the first time a matching file is touched.
  *
- * A delivered rule lives in the conversation rather than the system prompt, so anything that rewrites
- * or replaces the conversation can remove it. The delivery record is therefore reset whenever that
- * happens, and the rule is delivered again the next time one of its files is touched.
+ * The universal rules are a large, fixed cost on every turn (about 26k tokens), which is why a session that
+ * only wants path guidance and the hooks should load `cratis-path-guidance` and `cratis-hooks` instead.
  */
 export default function (pi: ExtensionAPI): void {
-    const delivered = new Set<string>();
-
-    // Compaction summarizes the conversation, which can drop an injected rule while leaving the
-    // delivery record claiming it is present; a switch replaces the conversation outright. Without
-    // this reset a long session would silently lose its scoped rules and never see them again.
-    const reset = () => {
-        delivered.clear();
-    };
-    pi.on('session_start', reset);
-    pi.on('session_compact', reset);
-    pi.on('session_before_switch', reset);
-
     pi.on('before_agent_start', (event, context) => ({
         systemPrompt: `${event.systemPrompt}\n\n${universalRules(context.cwd).map(rule => rule.content).join('\n\n')}`,
     }));
-
-    pi.on('tool_result', (event, context) => {
-        if (event.isError) return;
-        const paths = touchedPaths(event.toolName, (event as { input?: unknown }).input, context.cwd);
-        if (paths.length === 0) return;
-        const pending: ManagedRule[] = [];
-        const matched: string[] = [];
-        for (const path of paths) {
-            const relativePath = relative(context.cwd, resolve(context.cwd, path));
-            if (!relativePath || relativePath.startsWith('..')) continue;
-            for (const rule of rulesForPath(context.cwd, relativePath)) {
-                if (delivered.has(rule.name) || pending.some(candidate => candidate.name === rule.name)) continue;
-                pending.push(rule);
-                if (!matched.includes(relativePath)) matched.push(relativePath);
-            }
-        }
-        if (pending.length === 0) return;
-        pending.forEach(rule => delivered.add(rule.name));
-        const existing = Array.isArray(event.content) ? event.content : [];
-        return {
-            content: [
-                ...existing,
-                {
-                    type: 'text',
-                    text: `\n\n[cratis-rules] Rules that apply to ${matched.map(path => path.split(sep).join('/')).join(', ')}:\n\n${pending.map(rule => rule.content).join('\n\n')}`,
-                },
-            ],
-        };
-    });
 }

package/package/corpus/harnesses/pi/extensions/shared/AiConfiguration.ts

@@ -0,0 +1,8 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The parts of a repository's `.cratis/ai.json` that rule and skill selection read. */
+export interface AiConfiguration {
+    profiles?: string[];
+    languages?: string[];
+}

package/package/corpus/harnesses/pi/extensions/shared/ManagedRule.ts

@@ -0,0 +1,13 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export interface ManagedRule {
+    /** Path relative to the rules root, e.g. `code-quality-csharp.md` or `project/running-the-local-stack.md`. */
+    name: string;
+    /** Full file content, frontmatter included, exactly as the other harnesses receive it. */
+    content: string;
+    /** `application`, `framework`, or undefined when the rule is not profile-specific. */
+    profile?: string;
+    /** Globs from `applyTo` and `paths`. Empty means the rule applies to every file. */
+    globs: string[];
+}

package/package/corpus/harnesses/pi/extensions/shared/corpusRoot.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * The corpus this extension tree ships in: `.cratis/ai` for a managed installation and the repository,
+ * `package/corpus` inside the published `@cratis/pi` package. Both place `harnesses/pi/extensions/shared`
+ * four levels below it.
+ */
+export const corpusRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');

package/package/corpus/harnesses/pi/extensions/shared/frontmatter.ts

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export function unquote(value: string): string {
+    return value.trim().replace(/^["']|["']$/g, '');
+}
+
+/**
+ * Reads the YAML-ish frontmatter the corpus uses: scalar `key: value` lines and `key:` followed by
+ * `  - item` lines. Anything richer is not used by the rules and skills and is deliberately not supported.
+ */
+export function frontmatter(content: string): Map<string, string[]> {
+    const fields = new Map<string, string[]>();
+    if (!content.startsWith('---\n')) return fields;
+    const end = content.indexOf('\n---\n', 4);
+    if (end < 0) return fields;
+    let current: string | undefined;
+    for (const line of content.slice(4, end).split('\n')) {
+        const item = /^\s+-\s+(.*)$/.exec(line);
+        if (item && current) {
+            fields.get(current)!.push(unquote(item[1]));
+            continue;
+        }
+        const scalar = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(line);
+        if (!scalar) continue;
+        current = scalar[1];
+        const value = unquote(scalar[2]);
+        fields.set(current, value ? value.split(',').map(unquote).filter(Boolean) : []);
+    }
+    return fields;
+}

package/package/corpus/harnesses/pi/extensions/shared/globs.ts

@@ -0,0 +1,62 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** Globs that match every file. A rule or skill that declares one is not scoped to a path. */
+export const universalGlobs = new Set(['**', '**/*', '*']);
+
+function escapeRegExp(text: string): string {
+    return text.replace(/[.+^$()|[\]\\]/g, '\\$&');
+}
+
+/** Converts the glob dialect used by `applyTo` and `paths` (`**`, `*`, `?`, `{a,b}`) into an anchored RegExp. */
+export function globToRegExp(glob: string): RegExp {
+    let pattern = '';
+    for (let index = 0; index < glob.length; index++) {
+        const character = glob[index];
+        if (character === '*') {
+            if (glob[index + 1] === '*') {
+                if (glob[index + 2] === '/') {
+                    pattern += '(?:.*/)?';
+                    index += 2;
+                } else {
+                    pattern += '.*';
+                    index += 1;
+                }
+            } else {
+                pattern += '[^/]*';
+            }
+        } else if (character === '?') {
+            pattern += '[^/]';
+        } else if (character === '{') {
+            const close = glob.indexOf('}', index);
+            if (close > index) {
+                pattern += `(?:${glob.slice(index + 1, close).split(',').map(part => escapeRegExp(part.trim())).join('|')})`;
+                index = close;
+            } else {
+                pattern += '\\{';
+            }
+        } else {
+            pattern += escapeRegExp(character);
+        }
+    }
+    return new RegExp(`^${pattern}$`);
+}
+
+/**
+ * Why a glob cannot scope a skill trigger, or undefined when it can. A trigger must be a non-empty,
+ * repository-relative, balanced glob that does not match every file, otherwise it would either never fire
+ * or fire on every write.
+ */
+export function globProblem(glob: string): string | undefined {
+    if (glob.trim().length === 0) return 'is empty';
+    if (glob !== glob.trim()) return 'has leading or trailing whitespace';
+    if (glob.startsWith('/') || glob.includes('\\')) return 'must be a repository-relative glob using forward slashes';
+    if (universalGlobs.has(glob)) return 'matches every file';
+    if (glob.split('{').length !== glob.split('}').length) return 'has unbalanced braces';
+    try {
+        globToRegExp(glob);
+    } catch {
+        return 'does not compile to a matcher';
+    }
+    return undefined;
+}

package/package/corpus/harnesses/pi/extensions/shared/rules.ts

@@ -0,0 +1,98 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import type { AiConfiguration } from './AiConfiguration.ts';
+import { corpusRoot } from './corpusRoot.ts';
+import { frontmatter } from './frontmatter.ts';
+import { globToRegExp, universalGlobs } from './globs.ts';
+import type { ManagedRule } from './ManagedRule.ts';
+
+function rulesRoot(cwd: string): string {
+    const managedRoot = join(cwd, '.cratis', 'ai', 'rules');
+    return existsSync(managedRoot) ? managedRoot : join(corpusRoot, 'rules');
+}
+
+function configuration(cwd: string): AiConfiguration | undefined {
+    const path = join(cwd, '.cratis', 'ai.json');
+    if (!existsSync(path)) return undefined;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8')) as AiConfiguration;
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * A profile-specific rule is kept only when the repository selects that profile. Repositories without
+ * a `.cratis/ai.json` keep every rule, matching the `@cratis/pi` package.
+ */
+function matchesProfile(rule: ManagedRule, selected: AiConfiguration | undefined): boolean {
+    if (!rule.profile || !selected) return true;
+    const profiles = selected.profiles ?? [];
+    if (rule.profile === 'application') return profiles.some(profile => profile.startsWith('cratis/application'));
+    if (rule.profile === 'framework') return profiles.some(profile => profile.startsWith('cratis/engineering'));
+    return true;
+}
+
+/**
+ * The packaged `@cratis/pi` corpus holds every rule, so the languages and documentation a repository selected
+ * decide which apply: a rule scoped to `.cs` files needs `csharp`, to `.ts` files needs `typescript`, and to
+ * Markdown needs the `cratis/documentation` profile. A repository that selects no languages keeps them all.
+ */
+function matchesSelection(name: string, applyTo: string[], selected: AiConfiguration | undefined): boolean {
+    const languages = selected?.languages ?? [];
+    if (!selected || languages.length === 0) return true;
+    const scope = applyTo.join(',');
+    const needsCSharp = scope.includes('.cs');
+    const needsTypeScript = scope.includes('.ts') || name === 'rtk.md' || name.endsWith('/rtk.md');
+    const needsDocumentation = scope.includes('md');
+    if (!needsCSharp && !needsTypeScript && !needsDocumentation) return true;
+    return (needsCSharp && languages.includes('csharp')) ||
+        (needsTypeScript && languages.includes('typescript')) ||
+        (needsDocumentation && (selected.profiles ?? []).includes('cratis/documentation'));
+}
+
+/**
+ * Loads every managed rule with its frontmatter interpreted, filtered to the repository's profiles. From the
+ * packaged corpus, which is not resolved for the repository, the selected languages and documentation apply as
+ * well. A managed `.cratis/ai/rules` is already resolved by the CLI, so that second filter is skipped there.
+ */
+export function managedRules(cwd: string): ManagedRule[] {
+    const root = rulesRoot(cwd);
+    const selected = configuration(cwd);
+    const resolved = existsSync(join(cwd, '.cratis', 'ai', 'rules'));
+    return readdirSync(root, { recursive: true, encoding: 'utf8' })
+        .filter((entry): entry is string => entry.endsWith('.md'))
+        .sort()
+        .map(entry => {
+            const content = readFileSync(join(root, entry), 'utf8');
+            const fields = frontmatter(content);
+            return {
+                rule: {
+                    name: entry.split(sep).join('/'),
+                    content,
+                    profile: fields.get('profile')?.[0],
+                    globs: [...(fields.get('applyTo') ?? []), ...(fields.get('paths') ?? [])],
+                } satisfies ManagedRule,
+                applyTo: fields.get('applyTo') ?? [],
+            };
+        })
+        .filter(({ rule, applyTo }) => matchesProfile(rule, selected) && (resolved || matchesSelection(rule.name, applyTo, selected)))
+        .map(({ rule }) => rule);
+}
+
+/** Rules that apply to every file. These belong in the system prompt. */
+export function universalRules(cwd: string): ManagedRule[] {
+    return managedRules(cwd).filter(rule => rule.globs.length === 0 || rule.globs.some(glob => universalGlobs.has(glob)));
+}
+
+/** Rules whose `applyTo`/`paths` match a repository-relative path. These are delivered when that file is touched. */
+export function rulesForPath(cwd: string, relativePath: string): ManagedRule[] {
+    const normalized = relativePath.split(sep).join('/');
+    return managedRules(cwd).filter(rule =>
+        rule.globs.length > 0 &&
+        !rule.globs.some(glob => universalGlobs.has(glob)) &&
+        rule.globs.some(glob => globToRegExp(glob).test(normalized)));
+}

package/package/corpus/harnesses/pi/extensions/shared/skillFrontmatter.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * The `SKILL.md` frontmatter key that lists the globs a skill is hinted for. It is deliberately Cratis-specific:
+ * Claude Code gives a plain `paths` key in `SKILL.md` a meaning of its own (a "conditional skill" that stays out
+ * of the skill list until a matching file is touched), and `.claude/skills` exposes this corpus to it.
+ */
+export const skillTriggerKey = 'cratis-hint-paths';

package/package/corpus/harnesses/pi/extensions/shared/skillSelection.ts

@@ -0,0 +1,67 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { AiConfiguration } from './AiConfiguration.ts';
+import { corpusRoot } from './corpusRoot.ts';
+
+interface Profile {
+    id: string;
+    composes?: string[];
+    availableTargets?: string[];
+    languages?: string[];
+}
+
+interface Catalog {
+    publicProfiles: Profile[];
+    engineeringProfiles: Profile[];
+}
+
+/** The catalog beside the repository corpus (`.cratis/ai`), or beside `package/corpus` in the published package. */
+function catalog(): Profile[] | undefined {
+    const path = [join(corpusRoot, 'profile-catalog.json'), join(corpusRoot, '..', 'profile-catalog.json')].find(existsSync);
+    if (path === undefined) return undefined;
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as Catalog;
+    return [...parsed.publicProfiles, ...parsed.engineeringProfiles];
+}
+
+function supportsLanguage(profile: Profile, languages: Set<string>): boolean {
+    if (!profile.languages?.length) return true;
+    return profile.languages.some(language => language === 'language-agnostic' || languages.has(language));
+}
+
+/**
+ * The skills the packaged `@cratis/pi` makes available for a repository, resolved from `.cratis/ai.json` and the
+ * profile catalog exactly as `selectedSkillPaths` in `@cratis/pi` does (a repository without `ai.json` gets every
+ * catalog skill, because that is what the package loads for it). Undefined when the selection cannot be resolved,
+ * so a caller hints nothing rather than guessing.
+ *
+ * This mirrors `Source/Pi.Plugin/src/index.ts`, which cannot import from the corpus in both the repository and
+ * the published layout; a specification keeps the two in step.
+ */
+export function selectedSkillNames(cwd: string): string[] | undefined {
+    try {
+        const profiles = catalog();
+        if (profiles === undefined) return undefined;
+        const configurationPath = join(cwd, '.cratis', 'ai.json');
+        if (!existsSync(configurationPath)) {
+            return [...new Set(profiles.flatMap(profile => profile.availableTargets ?? []))].sort();
+        }
+        const configuration = JSON.parse(readFileSync(configurationPath, 'utf8')) as AiConfiguration;
+        const languages = new Set(configuration.languages ?? []);
+        const selected = new Set<string>();
+        const select = (id: string, explicitSelection: boolean): void => {
+            const profile = profiles.find(candidate => candidate.id === id);
+            if (!profile) throw new Error(`Unknown Cratis AI profile '${id}'.`);
+            if (!explicitSelection && !supportsLanguage(profile, languages)) return;
+            if (selected.has(id)) return;
+            selected.add(id);
+            profile.composes?.forEach(child => select(child, false));
+        };
+        configuration.profiles?.forEach(profile => select(profile, true));
+        return [...new Set(profiles.filter(profile => selected.has(profile.id)).flatMap(profile => profile.availableTargets ?? []))].sort();
+    } catch {
+        return undefined;
+    }
+}

package/package/corpus/skills/cratis-application-react-specifications/SKILL.md

@@ -2,6 +2,9 @@
 name: cratis-application-react-specifications
 description: Write specifications for the React and TypeScript surface of a Cratis application slice — view models, helpers, command orchestration, and narrow component behavior — using Vitest with Mocha-style describe/it, Sinon, and the Chai should interface. Use when adding or changing frontend behavior in an application that consumes Cratis. Do not use for backend scenarios or for specifications inside a Cratis framework package.
 license: MIT
+cratis-hint-paths:
+  - "**/for_*/**/*.ts"
+  - "**/for_*/**/*.tsx"
 ---
 
 # Cratis application React specifications

package/package/corpus/skills/cratis-application-slice-specifications/SKILL.md

@@ -2,6 +2,9 @@
 name: cratis-application-slice-specifications
 description: Specify the backend behavior of an event-sourced Cratis application slice with the in-process scenario family — CommandScenario, EventScenario, ReadModelScenario and ReactorScenario — including what to cover for each slice type and where the specification files live. Use when adding or changing backend behavior in an application built on Cratis. Do not use for framework library specifications and do not use for frontend behavior.
 license: MIT
+cratis-hint-paths:
+  - "**/when_*/**/*.cs"
+  - "**/for_*/**/*.cs"
 ---
 
 # Cratis application slice specifications

package/package/corpus/skills/cratis-documentation-writing/SKILL.md

@@ -2,6 +2,8 @@
 name: cratis-documentation-writing
 description: Plan, write, and improve user-centered Cratis documentation with a clear reader journey and one primary Diátaxis purpose per page. Use for product docs, tutorials, how-to guides, reference, explanations, and documentation reviews. For executable examples use cratis-technical-examples; for release notes use cratis-release-notes. Do not invent APIs or publish content.
 license: MIT
+cratis-hint-paths:
+  - "**/Documentation/**/*.{md,mdx}"
 ---
 
 # Documentation writing

package/package/corpus/skills/cratis-engineering-docs-authoring/SKILL.md

@@ -2,6 +2,8 @@
 name: cratis-engineering-docs-authoring
 description: Draft accurate Cratis product or engineering documentation once the reader's goal, owning source, and product evidence are known. Use for tutorials, how-to guides, explanations, and references; use the owning repository's navigation and visual QA workflows for placement and rendering.
 license: LICENSE
+cratis-hint-paths:
+  - "**/Documentation/**/*.{md,mdx}"
 ---
 
 # Cratis documentation authoring

package/package/corpus/skills/cratis-specifications-csharp/SKILL.md

@@ -2,6 +2,8 @@
 name: cratis-specifications-csharp
 description: Write C# specifications with Cratis.Specifications using the Establish/Because/should_ pattern and the for_/when_/and_ folder hierarchy. Use when adding or restructuring C# specs in any Cratis repository, choosing between an isolated unit spec and an in-process scenario spec, or building reusable given/ contexts. Do not use for TypeScript or React specs, and do not use it to decide what a command, projection, or reactor should do.
 license: MIT
+cratis-hint-paths:
+  - "**/for_*/**/*.cs"
 ---
 
 # Cratis C# specifications

package/package/corpus/skills/cratis-specifications-typescript/SKILL.md

@@ -2,6 +2,9 @@
 name: cratis-specifications-typescript
 description: Write TypeScript specifications in the Cratis BDD style using the given() helper, reusable context classes, Sinon stubbing, and the Chai .should fluent interface. Use when adding or restructuring TypeScript specifications, building a given/ context class, or laying out a for_/when_ specification folder. Do not use for C# specifications, and do not use it to decide what the code under specification should do.
 license: MIT
+cratis-hint-paths:
+  - "**/for_*/**/*.ts"
+  - "**/for_*/**/*.tsx"
 ---
 
 # Cratis TypeScript specifications

package/package/corpus/skills/cratis-technical-examples/SKILL.md

@@ -2,6 +2,8 @@
 name: cratis-technical-examples
 description: Design and verify developer-facing code samples, tutorial projects, and documentation snippets against real Cratis APIs. Use when adding or reviewing a runnable example, multi-client snippet, sample app, command/output pair, or migration before/after code. Do not invent API shapes or treat rendering as a compilation check.
 license: MIT
+cratis-hint-paths:
+  - "**/Samples/**/*.{cs,ts,tsx}"
 ---
 
 # Technical examples readers can trust

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.1.5",
+  "version": "7.2.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [
@@ -41,6 +41,7 @@
       "./src/index.ts",
       "./package/corpus/harnesses/pi/extensions/cratis-hooks/index.ts",
       "./package/corpus/harnesses/pi/extensions/cratis-mcp/index.ts",
+      "./package/corpus/harnesses/pi/extensions/cratis-path-guidance/index.ts",
       "./package/corpus/harnesses/pi/extensions/subagent/index.ts"
     ]
   }

package/src/index.ts

@@ -88,6 +88,16 @@ function ruleMatchesConfiguration(path: string, content: string, configuration:
         (needsDocumentation && selectedProfiles.includes('cratis/documentation'));
 }
 
+/**
+ * A rule scoped by `applyTo` to particular files is delivered by the packaged `cratis-path-guidance`
+ * extension when such a file is touched, so it stays out of the system prompt. Only rules that apply to
+ * every file, or declare no scope, belong there.
+ */
+function isUniversalRule(content: string): boolean {
+    const applyTo = (frontmatterValue(content, 'applyTo') ?? '').split(',').map(glob => glob.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+    return applyTo.length === 0 || applyTo.some(glob => ['**', '**/*', '*'].includes(glob));
+}
+
 function rules(cwd: string): string {
     const root = join(corpusRoot, 'rules');
     const configurationPath = join(cwd, '.cratis', 'ai.json');
@@ -99,6 +109,7 @@ function rules(cwd: string): string {
         .sort()
         .map(entry => ({ path: join(root, entry), content: readFileSync(join(root, entry), 'utf8') }))
         .filter(rule => !configuration || ruleMatchesConfiguration(rule.path, rule.content, configuration))
+        .filter(rule => isUniversalRule(rule.content))
         .map(rule => rule.content)
         .join('\n\n');
 }