@introspection-ai/operator
The Introspection Operator: a Recipe and skills that build an agent with its owner (brainstorm, draft and review).
Package details
Install @introspection-ai/operator from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@introspection-ai/operator- Package
@introspection-ai/operator- Version
0.4.5- Published
- Nov 22, 2026
- Downloads
- 7,129/mo · 1,707/wk
- Author
- yoga-introspection
- License
- Apache-2.0
- Types
- extension, skill, prompt
- Size
- 716.1 KB
- Dependencies
- 0 dependencies · 6 peers
Pi manifest JSON
{
"issues": [
{
"provider": "introspection"
}
],
"skills": [
"skills"
],
"prompts": [
"prompts"
],
"channels": [
{
"commands": [
"reply",
"send",
"list",
"read",
"react",
"fetch_file"
],
"provider": "slack"
}
],
"documents": [
{
"format": "docx"
},
{
"format": "pdf"
}
],
"extensions": [
"extensions/workspace",
"extensions/runtime"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
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.
| Folder | What it is |
|---|---|
skills/ |
The Operator's skills, published in @introspection-ai/operator |
SYSTEM.md, agents/ |
The Operator Recipe: the repository root is the Recipe, so its skills are the ones in skills/. agents/build.yaml runs build end to end, then deploy, and improve for an agent that is already deployed: see Run build locally |
evals/ |
The evals that measure each loop (to come) |
docs/ |
DESIGN.md: what the Operator is being rebuilt to, and the decisions still open |
Choose a skill
Each skill is one step of a phase, and each step's last instruction names the next.
| Phase | Skill | Use it to |
|---|---|---|
| onboarding | onboarding | Set a new project up from nothing: where the code lives, how the team talks, which workspace suite it uses. |
| onboarding | onboarding-repository | Choose GitHub (a new or existing repository) or Introspection for the agent's code. |
| onboarding | onboarding-issues | Choose Linear, Jira (to follow) or Introspection for tracking work, and connect Linear. |
| onboarding | onboarding-collaboration | Connect Slack (Teams to follow) so the team can talk to its agents. |
| onboarding | onboarding-productivity | Connect Google Workspace (Office 365 to follow): the project's connector and the person's own account. |
| build | build-brainstorm | Start a new agent: draft its cases from the owner's own material, ask only about the gaps, and get the cases approved. |
| build | build-draft | Write the agent from its approved cases, locally, and run the cases until they pass. |
| build | build-review | Review the drafted agent with fresh-context reviewers, fix what they find, and package it as a pull request. |
| build | build-migrate | Placeholder, not in any flow yet: start an agent from one on another harness (eve, Deep Agents, Claude Code or Codex skills). Its playbooks are still to write. |
| deploy | deploy-connect | Deploy starts here: check the CLI, login and scopes, then connect the MCP servers the Recipe declares, or fake them with introspection dev --mcp. |
| deploy | deploy-create | Choose the repository with the owner, land the branch on main and create the runtime. |
| deploy | deploy-test | Run on the version only what the platform must prove, report it and hand the owner the chat link. |
| deploy | deploy-try | Give the owner a chat with the version built from a branch's head commit, without pinning anything. |
| improve | improve-select | Choose the deployed agent and the one version to improve, with each version's conversations over the last 14 days. |
| improve | improve-classify | Read the version's eval baseline, tool errors, annotations, feedback, judgements and observations, rank the failure modes, and have the owner pick one. |
| improve | improve-baseline | Open the failure mode's issue I-…, cut pr/improve-I-… from the deployed commit, and set the baseline, with up to three new approved cases. |
| improve | improve-propose | The owner picks one of up to three remedies; a proposer writes it without the evals, a fresh reviewer accepts it, cloud trials prove it, and the pull request opens. |
| improve | improve-simulate | Only when asked: hold simulated conversations with a deployed agent toward the owner's outcome, review each with one gap or good, and synthesize their observations. |
| optimize | optimize-quality | Search candidate changes against the approved cases held fixed, with proposal and review subagents, and keep one that beats the noise and passes the held-out cases: the quality floor. |
| optimize | optimize-cost | Find the cheapest version that holds the quality floor, measured per completed task: the cost ceiling. |
| optimize | optimize-latency | Find the fastest version that holds both, check recent production traffic, and hand the branch with its measured trade-off to deploy. |
| platform | platform-triage | Take a message from Slack, the app's chat or a routine: answer it, or open the issue that tracks the work and say what happens next. |
| platform | platform-investigate | Find which agent and what kind of cause across the organization, read-only, and record it on the issue; one agent's evidence is improve's. |
| platform | platform-resolve | Launch the agent that does the work, follow it to a reviewed result, tell whoever raised it and close the issue. |
| platform | platform-issues | Keep an issue: open or continue it, add evidence, ask a person, hand a pull request over for review, and close it. |
| routines | routines-schedule | Create, change or pause a routine so work happens later, recurs or answers an event (Slack, GitHub, a webhook connector). |
| routines | routines-respond | Do a firing routine's assignment and report it, or stay quiet. |
| routines | routines-adjust | Change a routine's prompt, schedule or triggers from what its runs showed, or pause or resume it. |
| eval | eval-case | Write or change a case's goal file, evals/cases/<id>.md, including one taken from a real conversation, and get it approved. |
| eval | eval-author | Write a case's implementation and its verifier, for Vitest or Harbor, producing reward.json and reward-details.json. |
| eval | eval-simulate | Simulate the bindings an eval needs (MCP servers today): the fakes/ layout, the contract, scenarios and drift checks. |
| eval | eval-run | Run a suite with introspection eval run and read run.json: incomplete cases, trials, retries and replays. |
| eval | eval-compare | Compare two runs case by case, keep a baseline, and gate a pull request on it. |
The eval-* steps are the mechanics every phase uses to write, run and compare cases and to simulate their bindings; 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
uvis installed. The Operator has no Python of its own: each documents package brings its own, and Pi builds it when the session starts. - Shared documents: it creates
files/andoutputs/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/filesand/workspace/outputs. Put the documents you'll share infiles/: the documents tool opens files only inside the build folder. Given a path elsewhere, the agent copies the file intofiles/first. - Versions: it checks that Pi's
@introspection-ai/recipessatisfies thepeerDependenciesrange, and says to runintrospection upgradewhen 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 init starts the same session from the Operator the CLI keeps in ~/.introspection/operator, installing it the first time; introspection setup installs it too.
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/workspace) act only where Recipes loads them: it asks Recipes for its session (getRecipeSessionContext), and an instance Pi loaded as a plain package has none, so it registers nothing. It acts only in the Operator's ownbuildsession. - Runtime extensions (
extensions/runtime) are for the Introspection platform only: the labelledshelltool, recording the GitHub pull requests a task opens (pr_urls), and acknowledging the Slack message a task answers. They act only for theoperatoragent in a platform task (INTROSPECTION_TASK_ID); anywhere else they register nothing. - The platform's agent (
agents/operator.yaml) is the one the Introspection platform runs, with its model, the Slackchannelstool (pi.channels) and theissuestool (pi.issues). Their provider packages are peers the platform's image installs; locally they stay inactive, sincebuildlists neither tool. - Skills are listed in
pi.skills, because an explicitpiblock turns off Pi's discovery ofskills/. Pi then offers them in every session, including an owner's own Recipe runs. Pass--no-skillsto 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:
| Phase | Skills | What the phase covers | Status |
|---|---|---|---|
build |
build-brainstorm, build-draft, build-review |
Create a new agent: ask until the design is clear, write it up locally, end with a pull request ready for review, and deploy it to staging | First version in skills/; replaces today's create (migrate is an open decision in docs/MIGRATION.md) |
deploy |
deploy-connect, deploy-create, deploy-test, deploy-try |
Connect a pull request's Recipe to its data, put it on a runtime, and hand the owner a chat with it | Built: deploy-connect, deploy-create, deploy-test, deploy-try |
improve |
improve-select, improve-classify, improve-baseline, improve-propose |
Turn traces from testing and production into cases, and propose changes with evidence | Designed; replaces today's improve and operate |
optimize |
optimize-quality, optimize-cost, optimize-latency |
Raise quality, then cut cost, then latency, each holding the gains of the one before | Built: optimize-quality, optimize-cost, optimize-latency; replaces today's optimize |
harden |
harden-scan, harden-spar, harden-stress |
Last, and optional apart from the scan: check the Recipe against the OWASP Agentic Skills Top 10, spar with it as a red team, and test it under load; failures become permanent cases | Designed; new, with no workflow behind it today |
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, except to a subagent's brief in agents/, or to a missing file, every reference linked, every step name a folder, no private issue or PR numbers), that every subagent the skills start has a linked agents/<name>-brief.md that no skill writes out, and that exactly the Recipe and its launcher are packed: skills/, agents/, prompts/, 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.