@introspection-ai/operator

The Introspection Operator: a Recipe and skills that build an agent with its owner (brainstorm, draft and review).

Packages

Package details

extensionskillprompt

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 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.
  • 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 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 own build session.
  • Runtime extensions (extensions/runtime) are for the Introspection platform only: the labelled shell tool, recording the GitHub pull requests a task opens (pr_urls), and acknowledging the Slack message a task answers. They act only for the operator agent 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 Slack channels tool (pi.channels) and the issues tool (pi.issues). Their provider packages are peers the platform's image installs; locally they stay inactive, since build lists neither tool.
  • 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:

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.