Introspection Operator

The Operator is the agent that builds, deploys and improves other agents (Recipes) on Introspection. This repository holds the Operator: its Recipe, its skills and the evals that measure it, so a change to how the Operator works and the evidence that it helps land in the same pull request. Everything here is written from scratch; nothing is carried over from the previous Operator.

Choose a skill

Each skill is one step of a phase, and each step's last instruction names the next.

The eval-* steps are the mechanics every phase uses to write, fake, run and compare cases; they aren't a phase of their own. Outside an Operator session, introspection evals <step> prints one.

Run build

You need Node 24, uv and credentials for the model in agents/build.yaml (sign in once with /login in Pi).

npm i -g @introspection-ai/cli && introspection setup   # once: Pi and the Recipes release it needs
npx @introspection-ai/operator                          # a new agent, in ~/.introspection/agents/new-<n>
npx @introspection-ai/operator ~/work/my-agent          # start or resume a build in that folder
npx @introspection-ai/operator ~/work/my-agent --model <model>   # flags after the folder go to Pi

npx @introspection-ai/operator runs the package's launcher, bin/introspection-operator.js. It starts the build agent (pi --recipe <the package> --agent build --no-context-files) in a folder of its own, because build treats the folder it starts in as the owner's workspace: it creates the agent's repository there and resumes from what it finds there.

• No AGENTS.md or CLAUDE.md: it turns off Pi's loading of those files from that folder and the folders above it. They're written for coding agents and can describe other agents, which build must not copy.
• Folder safety: it refuses a folder inside the package or nested in another git repository; the agent's own repository is allowed, to resume.
• Python: it checks that uv is installed. The Operator has no Python of its own: each documents package brings its own, and Pi builds it when the session starts (Recipes 0.39.0 and later).
• Shared documents: it creates files/ and outputs/ in the build folder, beside the agent's repository. The Recipe's workspace extension (extensions/workspace) tells the agent where they are, as the cloud does with /workspace/files and /workspace/outputs. Put the documents you'll share in files/: the documents tool opens files only inside the build folder. Given a path elsewhere, the agent copies the file into files/ first.
• Versions: it checks that Pi's @introspection-ai/recipes satisfies the peerDependencies range, and says to run introspection upgrade when it doesn't.

Set INTROSPECTION_AGENTS_DIR to put new builds somewhere other than ~/.introspection/agents.

In a checkout of this repository, pnpm build runs the same launcher, and installs the dependencies with pnpm once.

The launcher is being retired. introspection local, in a folder with no Recipe, starts the same session from the copy pi install npm:@introspection-ai/operator puts in Pi's package folder, which introspection setup installs.

Installed with pi install

package.json#pi is read twice: by Recipes when the package runs as a Recipe, and by Pi when it's installed as a Pi package, which loads its extensions and skills in every session.

• Extensions (extensions/case-runs, extensions/workspace) act only where Recipes loads them: each asks Recipes for its session (getRecipeSessionContext), and an instance Pi loaded as a plain package has none, so it registers nothing. The workspace extension acts only in the Operator's own build session.
• Skills are listed in pi.skills, because an explicit pi block turns off Pi's discovery of skills/. Pi then offers them in every session, including an owner's own Recipe runs. Pass --no-skills to a Recipe launch to keep them out: Recipes still adds the Recipe's own skills.

Package

@introspection-ai/operator is the npm package published from this repository's root. It contains the Recipe a person runs (SYSTEM.md, agents/, skills/ and extensions/) and its launcher (bin/), so npx @introspection-ai/operator starts a build, and npx skills sync finds the skills in it. docs/, scripts/ and the evals are never published.

Phase skills are grouped by the stage of an agent's life (see docs/DESIGN.md), and the phase is the prefix of each skill's name, because npx skills sync finds skills only at skills/<name>/SKILL.md and not in nested folders:

Evals aren't a phase. Each phase's steps decide when to evaluate and what passes; how to write and run a case is in the eval-* steps in skills/, which version with the Operator so its own evals measure them (see docs/DESIGN.md).

Releases are cut by release-please (.github/workflows/release.yml): Conventional Commit titles on main update a release pull request, and merging it tags operator-vX.Y.Z and publishes to npm through trusted publishing, starting at 0.1.0. CI runs node scripts/check-skills.mjs (frontmatter, folder names, that the "Choose a skill" table above has one row per skill folder, that each agent's skills list holds every skill its skills name, that each skill folder stands alone (no link out of it or to a missing file, every reference linked, every step name a folder, no private issue or PR numbers), and that exactly the Recipe and its launcher are packed: skills/, agents/, extensions/, SYSTEM.md and bin/introspection-operator.js; that pi.skills lists skills; and that there's no pi.runtime.python) and npm pack --dry-run; publishing also requires at least one skill.

License

What @introspection-ai/operator publishes (SYSTEM.md, agents/, skills/ and bin/) is licensed under the Apache License 2.0; see skills/LICENSE. Everything else in this repository is proprietary to Introspection and not licensed for use outside it.