Cratis AI integration for Pi
This is the plugin path for repositories that do not use cratis ai.
Install it into a Pi project:
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, 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.
The subagent tool stands down for the session when another extension already
provides a delegation tool named Agent (such as pi-subagents, which lists the
same agents). It removes itself from the active tools at session start and
shows one notice when Pi has a UI, so the model is not offered two delegation
tools. The package declares generated Pi-native agents through pi.subagents.agents
for external loaders that support package resources. Their comma-separated tools:
allowlists already use Pi names (read, grep, find, bash, edit, write),
so neither loader needs to interpret Claude-style names. See
Agent adapters for regeneration and drift checks.
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
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.
MCP servers from the corpus
The packaged cratis-mcp extension starts every stdio server declared in
mcp-servers.json whose profiles intersect the profiles listed explicitly in
.cratis/ai.json (a profile reached only through another profile's composes does
not start a server; Screenplay keeps its composed selection) (for
example codescene for cratis/codescene, playwright for cratis/playwright).
Each server gets its own connection, so one failing to start never stops the others,
and its tools are namespaced by server id (playwright_browser_navigate). The
command, args and optional literal env are used verbatim, without a shell. A
malformed selected server is skipped with one notice; set
mcpServers.<id>.enabled to false in .cratis/ai.json to opt a server out.
capabilities.json beside the extension declares this behavior to the Cratis CLI.
Screenplay MCP tools
The packaged cratis-mcp extension starts the Screenplay MCP server
(cratis screenplay mcp) when the resolved profiles include cratis/screenplay.
The backend application profiles compose it, so an application repository gets
the Screenplay skills and, when the Cratis CLI 3.46.1 or later is installed, the
Screenplay tools; the server creates no model folder until the first write.
Installing them does not opt the repository in to model-first work.
When Screenplay comes in only through such a profile and no model root is
configured, a missing CLI, a CLI older than 3.46.1 (which creates the model
folder at server start) or a server that fails to start leaves the Screenplay
tools inactive with one informational notice when Pi has a UI, and silently otherwise.
Selecting any profile that also reaches Screenplay without going through an application
profile (including cratis/screenplay, cratis/modeling/screenplay-stage,
cratis/full/* or cratis), or configuring mcpServers.screenplay.root in
.cratis/ai.json, keeps startup failures visible as errors.
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
metadata.cratis-hint-paths frontmatter (one string of whitespace-separated globs)
matches the file. (It sits under metadata because Agent Skills allows only a fixed set
of top-level keys, and 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:
extensions: cratis-path-guidance, cratis-hooks
The subagent tool of this package starts a full pi process and loads every
extension.