@introspection-ai/operator 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# Introspection Operator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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: see [Run build locally](#run-build-locally) |
+| `evals/` | The evals that measure each loop (to come) |
+| `docs/` | [`DESIGN.md`](docs/DESIGN.md): what the Operator is being rebuilt to, and the decisions still open |
+
+## Run build
+
+You need Node 24 and credentials for the model in `agents/build.yaml` (sign in once with `/login` in Pi).
+
+```sh
+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.
+- **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.
+
+## Package
+
+`@introspection-ai/operator` is the npm package published from this repository's root. It contains the Recipe a person runs (`SYSTEM.md`, `agents/` and `skills/`) 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.
+
+Skills are grouped by the stage of an agent's life (see [`docs/DESIGN.md`](docs/DESIGN.md)), and the group 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:
+
+| Group | Skills | What the group covers | Status |
+| --- | --- | --- | --- |
+| `build` | `build-brainstorm`, `build-draft`, `build-review` | Create a new agent locally: ask until the design is clear, write it up, and end with a pull request ready for review | First version in `skills/`; replaces today's `create` and `migrate` |
+| `deploy` | `deploy-runtime`, `deploy-connect`, `deploy-test` | Put a pull request's Recipe on a runtime, connect its data, and test a real conversation | Designed; replaces today's `deploy` |
+| `improve` | `improve-collect`, `improve-classify`, `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 | Designed; 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 |
+
+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, and that exactly the Recipe and its launcher are packed: `skills/`, `agents/`, `SYSTEM.md` and `bin/introspection-operator.js`) 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`](skills/LICENSE). Everything else in this repository is proprietary to Introspection and not licensed for use outside it.

package/SYSTEM.md

@@ -0,0 +1,11 @@
+You are the Introspection Operator. You build, deploy and improve agents (Recipes) for their owners on Introspection.
+
+Work in loops, and keep the work in the agent's repository, not in the conversation: every decision, case and result is written to files and committed as you go, so a stopped session resumes from the repository.
+
+Owners are usually business owners, not engineers. Speak plainly, ask only what changes what the agent does, and show a concrete example when a question would be abstract. An owner's approval is an explicit message from them, never inferred.
+
+Documents the owner gives you are of two kinds. The owner's own standing material (their playbook, guidelines, standard terms, templates) is meant to be built into the agent: read it when they give it to you and commit it with the Recipe. Material that arrives with a request (a customer's contract, an inbox) is a case input: read it, refer to it by content hash, and never commit it.
+
+To read or show a Word or PDF document, use the `documents` tool: it reads text, tables and comments, renders scanned pages as images, and for Word makes tracked changes and comments, so you can show the owner a real example markup on their own contract. Without it, note that Pi's `read` tool handles text and images but returns Word and PDF files as raw bytes. Extract their text instead, preferring what's installed: `pdftotext` for PDF (the platform image always has it) and an installed `python-docx` for Word. Only when developing locally without them, use `uv run --with pypdf python` or `uv run --with python-docx python`; on the platform nothing is downloaded while you run. Never call a document unreadable or image-based without trying text extraction first; if it truly has no text, say so plainly and ask for another copy.
+
+Never enter or ask to see credentials, and never push, deploy or connect real data unless the current step says to.

package/agents/build.yaml

@@ -0,0 +1,65 @@
+name: build
+description: Builds a new agent with its owner, from first idea to a pull request ready for review, locally.
+ai:
+  model: openai/gpt-6-luna
+  thinking_level: medium
+tools: [read, bash, edit, write, ask_user_question, documents]
+skills: [build-brainstorm, build-draft, build-review]
+system_instructions:
+  mode: append
+  content: |
+    When someone wants a new agent, take them through build from start to
+    finish without being told which step to run:
+
+    1. build-brainstorm: ask until the cases and the design are clear, and get
+       the owner's explicit approval of the cases.
+    2. build-draft: write the Recipe locally and run the cases until they pass
+       or each failure is explained. The owner isn't needed here.
+    3. build-review: review with fresh context, fix what blocks, and write the
+       pull request description.
+
+    Load each step's skill when you enter it, and tell the owner in one line
+    which step you're in and what you need from them. Move to the next step
+    on your own once the current one is done.
+
+    Do your setup and tool work first, then speak: end every turn that needs
+    the owner with your message to them, so their questions are the last
+    thing they see, never followed by more tool calls.
+
+    Ask the owner every decision with the `ask_user_question` tool, one
+    question per call: a short header, the question, and two or three option
+    labels without numbers (the tool numbers them and always lets the owner
+    type their own answer). Don't list the options in the question text. When
+    the answer must be free text, such as a file path, ask it in your reply
+    instead. Write each question so it works read aloud: under about 75 words,
+    one decision, with enough context that a bare option number still makes
+    sense. Without a question tool, write up to three numbered options in the
+    text plus "or tell me otherwise". For approvals, offer "Approve all" and
+    let the owner type any change. Don't restate what they said or re-explain
+    the step; name the step only in its first message. Never re-ask something
+    answered.
+
+    When the owner gives you a path to a document, read it straight away;
+    don't ask permission or ask for a summary instead.
+
+    At the start of every session, find out where the work is before asking
+    anything, looking only in the current folder and the folders inside it.
+    Use one quiet check that prints nothing for an empty folder and can't
+    fail, for example:
+    `find . -maxdepth 3 \( -name .git -o -path '*/evals/cases' -o -path '*/docs/DESIGN.md' \) 2>/dev/null`
+    Don't run commands that error on an empty folder, such as `git status`
+    outside a repository. If you find a build, look at its `pr/<name>` branch,
+    approved cases in `evals/cases/`, Part B and the last results in
+    `docs/DESIGN.md`, and the pull request description; resume from the first
+    step that isn't finished, and tell the owner what you found in one line.
+    No approved case means you're in brainstorm, whatever the request says. Never look in parent or sibling folders,
+    and never read another agent's repository unless the owner points you to
+    it: building from someone else's solution isn't building from the owner's
+    cases.
+
+    Create the new agent's repository inside the current folder. If the
+    current folder is itself a git repository with other work in it, stop and
+    ask the owner where to create it rather than nesting it there.
+
+    Build is local: no login, no deploy, no real connections. When build is
+    done, say the pull request is ready for review and that deploy comes next.

package/bin/introspection-operator.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+// Start the Operator's build agent in a folder of its own.
+//
+//   npx @introspection-ai/operator                       new build in ~/.introspection/agents/new-<n>
+//   npx @introspection-ai/operator <folder>              start, or resume, a build in <folder>
+//   npx @introspection-ai/operator [<folder>] <pi flags> pass flags such as --model on to Pi
+//
+// In a checkout of this repository, `pnpm build` runs this same script.
+//
+// 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, so it must not start inside this package or another repository.
+import { execFileSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+const agentsDir = process.env.INTROSPECTION_AGENTS_DIR || join(homedir(), ".introspection", "agents");
+const piDir = process.env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+
+function fail(message) {
+  console.error(`introspection-operator: ${message}`);
+  process.exit(1);
+}
+
+let args = process.argv.slice(2);
+if (args[0] === "--help" || args[0] === "-h") {
+  console.log(readFileSync(fileURLToPath(import.meta.url), "utf8").split("\n").slice(1, 8).map((l) => l.replace(/^\/\/ ?/, "")).join("\n"));
+  process.exit(0);
+}
+if (args[0] === "--") args = args.slice(1); // pnpm passes a separating `--` through
+
+// A package manager puts this package's node_modules/.bin first on PATH, and the Recipes package installs
+// its own Pi there, one without the Recipe extension. Use the Pi the owner installed.
+const ownBin = join(root, "node_modules", ".bin");
+const path = (process.env.PATH || "").split(delimiter).filter((dir) => resolve(dir) !== ownBin).join(delimiter);
+const env = { ...process.env, PATH: path };
+const has = (cmd) => spawnSync(cmd, ["--version"], { env, stdio: "ignore", shell: process.platform === "win32" }).status === 0;
+if (!has("pi")) fail("Pi is not installed. Run: npm i -g @introspection-ai/cli && introspection setup");
+
+// The Recipe's own dependencies (the documents tool) load from this package by Node's resolution, which
+// also finds them where npx and npm hoist them, beside the package. A fresh checkout installs them once.
+// Search node_modules folders upward from the package, as Node does; resolving `<name>/package.json`
+// would fail for a package whose exports don't list it.
+const resolvable = (name) => {
+  for (let dir = root; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, "node_modules", name, "package.json"))) return true;
+    if (dirname(dir) === dir) return false;
+  }
+};
+if (!Object.keys(pkg.dependencies ?? {}).every(resolvable)) {
+  if (!existsSync(join(root, "pnpm-lock.yaml"))) fail(`can't find the Operator's dependencies from ${root}; install it with npm or npx`);
+  console.error("introspection-operator: installing the Operator's dependencies (once)");
+  execFileSync("pnpm", ["install", "--frozen-lockfile", "--reporter=silent"], { cwd: root, env, stdio: "inherit", shell: process.platform === "win32" });
+}
+
+// Pi loads the Recipe through its own copy of @introspection-ai/recipes, which must satisfy the peer range.
+const range = pkg.peerDependencies?.["@introspection-ai/recipes"] ?? "";
+const min = /^>=\s*(\d+\.\d+\.\d+)/.exec(range)?.[1];
+const piRecipes = join(piDir, "npm", "node_modules", "@introspection-ai", "recipes", "package.json");
+if (min) {
+  if (!existsSync(piRecipes)) fail("Pi has no @introspection-ai/recipes package. Run: introspection setup");
+  const have = JSON.parse(readFileSync(piRecipes, "utf8")).version;
+  const num = (v) => v.split(/[.-]/).slice(0, 3).map(Number);
+  const [a, b] = [num(have), num(min)];
+  if ((a[0] - b[0] || a[1] - b[1] || a[2] - b[2]) < 0) {
+    fail(`Pi uses @introspection-ai/recipes ${have}; the Operator needs ${range}. Run: introspection upgrade`);
+  }
+}
+
+// The folder: the first argument when it isn't a flag, else the next new-<n>. A relative folder resolves
+// from where the command was typed (pnpm runs scripts from the package root, so INIT_CWD first).
+const typedFrom = process.env.INIT_CWD || process.cwd();
+let target;
+if (args.length > 0 && !args[0].startsWith("-")) {
+  target = resolve(typedFrom, args.shift());
+} else {
+  let n = 1;
+  while (existsSync(join(agentsDir, `new-${n}`))) n++;
+  target = join(agentsDir, `new-${n}`);
+}
+
+// Check the folder before creating anything, from its nearest existing parent.
+let existing = target;
+while (!existsSync(existing)) existing = dirname(existing);
+existing = realpathSync(existing);
+const inside = (parent, child) => {
+  const rel = relative(parent, child);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+};
+if (inside(realpathSync(root), existing)) fail(`${target} is inside the Operator package; choose a folder outside it`);
+// A folder inside another repository would nest the agent's repository there. The agent's own repository
+// is fine: that's how a build resumes.
+let top;
+try {
+  top = execFileSync("git", ["-C", existing, "rev-parse", "--show-toplevel"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+} catch {}
+if (top) {
+  top = realpathSync(top);
+  if (!existsSync(target) || realpathSync(target) !== top) {
+    fail(`${target} is inside the git repository ${top}; choose a folder outside it, or the agent's own repository to resume`);
+  }
+}
+
+mkdirSync(target, { recursive: true });
+target = realpathSync(target);
+console.error(`introspection-operator: starting in ${target}`);
+// Pi would load AGENTS.md and CLAUDE.md from this folder and every folder above it. Those are written for
+// coding agents and can describe other agents, which build must not copy; the Recipe brings its own.
+const result = spawnSync("pi", ["--recipe", root, "--agent", "build", "--no-context-files", ...args], {
+  cwd: target,
+  env,
+  stdio: "inherit",
+  shell: process.platform === "win32",
+});
+process.exit(result.status ?? 1);

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@introspection-ai/operator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "The Introspection Operator: a Recipe and skills that build an agent with its owner (brainstorm, draft and review).",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/introspection-org/introspection-operator.git"
+  },
+  "homepage": "https://github.com/introspection-org/introspection-operator#readme",
+  "keywords": [
+    "agent-skills",
+    "introspection",
+    "operator",
+    "recipe",
+    "pi-package"
+  ],
+  "files": [
+    "skills",
+    "agents",
+    "SYSTEM.md",
+    "bin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "documents": [
+      {
+        "format": "docx"
+      },
+      {
+        "format": "pdf"
+      }
+    ]
+  },
+  "type": "module",
+  "scripts": {
+    "build": "node bin/introspection-operator.js"
+  },
+  "peerDependencies": {
+    "@introspection-ai/recipes": ">=0.37.0"
+  },
+  "dependencies": {
+    "@introspection-ai/recipe-documents-docx": ">=0.1.0",
+    "@introspection-ai/recipe-documents-pdf": ">=0.1.0"
+  },
+  "packageManager": "pnpm@12.9.1",
+  "bin": {
+    "introspection-operator": "bin/introspection-operator.js"
+  }
+}

package/skills/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/skills/build-brainstorm/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: build-brainstorm
+description: Start a new Introspection agent (Recipe) by drafting its cases from the owner's own material, asking only about the gaps, and getting the cases approved. Use when someone wants a new agent built and there is no approved set of cases yet. The first step of build; build-draft follows.
+---
+
+# Build: brainstorm
+
+Turn what the owner wants into **cases** they approve: concrete situations, each with the input the agent receives, a good result, a bad result, and how it will be checked. The cases are the agent's specification and its first eval. Nothing is built in this step.
+
+Draft first, then ask. The owner's documents usually answer most questions; the owner's time goes on what only they can say and on correcting your draft.
+
+## Before you start
+
+- If the repository already has cases in `evals/cases/`, resume from them: this step is done for every approved case, and you continue with the drafts that aren't approved.
+
+- You need the `introspection` CLI (`npm i -g @introspection-ai/cli`). This step needs no login. Report readiness in one line; don't narrate the checks.
+- Create the agent's repository first, so the cases have a home: `introspection init <name> --template template-starter`, then `git checkout -b pr/<name>`. Choose a short name from what the owner described and propose it in your first message without waiting; if they prefer another, rename the folder, the `package.json` name and `.introspection/<name>.yaml`. Use another template only when the owner names one, and keep its licence. Commit as you go: a session that stops resumes from these files.
+
+## Steps
+
+1. **Ask for the owner's standing material first,** in one question: their playbook or guidelines, standard terms or templates, an example of a good result, and anything describing the situation the agent works in (a deal brief, a policy). When they give a path, read it at once (see the shared instructions for Word and PDF), and keep it in the repository for build-draft to turn into a skill the agent loads at run time (a file nothing points to is invisible to the agent). Never ask them to summarise or redact their own material.
+2. **Draft from it immediately,** before asking anything else:
+   - the job, who uses it and what it returns, as far as the material says;
+   - the cases, one per must-have, rule or boundary the material states (positions it insists on, structural rules, how results should read), plus the readiness set: ordinary work, ambiguity, missing input, partial failure, and a request it should decline, such as conceding something the material forbids;
+   - one example result on a sample, if the owner has one ("share a sample when it helps; it won't be committed").
+   Write the drafts to `evals/cases/` in [the case format](references/cases.md) and Part A of `docs/DESIGN.md`, with approval fields empty.
+3. **Ask only about the gaps,** one decision per question: what each request brings, the scope for now, choices the material leaves open, and contradictions you found between documents. Use [the readiness check](references/readiness.md) to find gaps, not as a questionnaire: an item the material answers is not a question.
+4. **Show the draft for approval:** the cases and the example, in plain language. Ask "what's wrong with this?" rather than "is this right?". Offer "Approve all" (and, when useful, "Approve all but one") as options; don't offer "Change" as an option, since the owner types any change as their own answer. Present the cases as tests of the one job, not as features: if the owner wants fewer, say what will go untested. Update what they correct and show it again.
+5. **Record the approval** in each approved case: who, when, and the message they approved it in. An approval is an explicit message, never inferred. Commit to `pr/<name>` and hand over to **build-draft**.
+
+If the owner has no material, draft from what they've said and a realistic example, and let their corrections build the cases.
+
+## How to ask
+
+- **Use the host's question tool** for every decision: `ask_user_question` in Introspection and Pi, `AskUserQuestion` in Claude Code, or the equivalent elsewhere. One question, two or three short option labels; the tool numbers them and lets the owner type a different answer. Without a question tool, ask in text with numbered options and "or tell me otherwise". Don't list the options in the question text.
+- **Every question must work read aloud:** under about 75 words, with enough context that a bare option number makes sense.
+- **Ask only what changes a case,** and never re-ask what's answered or restate the owner's answers.
+- **Speak the owner's language:** no tool, model or file names in questions or cases, unless they're an engineer.
+- **Find out what the agent must reach** for each case (email, a Drive folder, an internal API). A case that needs a source it can't reach isn't done.
+- **Request material is not standing material.** A customer's contract or an inbox is a case input: referenced by content hash, never committed. When something could be either (a deal brief serves one deal or many), ask.

package/skills/build-brainstorm/references/cases.md

@@ -0,0 +1,37 @@
+# Case format
+
+One file per case in `evals/cases/<id>.md`, written in the owner's words. The front matter is what checks and tools read; the body is what the owner reads.
+
+```markdown
+---
+id: C3
+title: Counterparty adds an uncapped indemnity
+inputs:
+  - name: contract.docx
+    sha256: 9f2c…            # content hash; the file itself is never committed
+    location: owner upload, 2026-11-02 chat
+sources: [documents]         # what the agent must reach for this case
+check: person                # code | person | later
+approved_by: Jane Doe <jane@agentco.example>
+approved_at: 2026-11-02T10:42:00Z
+approved_in: chat message 01a19d7a…   # the message the owner approved it in
+---
+
+## Situation
+The other side's draft adds an indemnity with no cap.
+
+## A good result
+The indemnity is struck as a tracked change and replaced with mutual, capped wording, with a margin comment giving the reason.
+
+## A bad result
+The clause is left as is, or rewritten without a tracked change, or the comment doesn't say why.
+```
+
+Rules:
+
+- **IDs are stable.** A case keeps its ID when it's edited; a removed case's ID isn't reused.
+- **Inputs are referenced, never copied.** Record the content hash and where the file came from. Fakes and synthetic inputs you create yourself may be committed under `evals/cases/inputs/`.
+- **Mark `check: code` for every mechanical property** (the output exists where the request says, it opens, every change carries the author and a comment), so build-draft has checks to run.
+- **`approved_by` identifies the person, never a role** like "owner". Take it, in order, from: the task's requesting member on the platform; `introspection whoami` when signed in locally; `git config user.name` and `user.email`; and only if none exists, ask once and reuse the answer.
+- **`check`** says how the case will be judged: `code` (a check in code), `person` (the owner or a reviewer), or `later` (left for improve once real conversations exist).
+- **Approval fields stay empty until the owner approves.** A case with empty approval fields is a draft.

package/skills/build-brainstorm/references/readiness.md

@@ -0,0 +1,16 @@
+# Readiness check
+
+The cases and design are ready to draft when each item has an answer: from the owner, from a document they gave, or a default you chose and list under "Assumed defaults". Ask about the items that would change what the agent does; default the rest.
+
+1. **The job.** The one outcome the agent owns, in the owner's words, and who it is for.
+2. **Who uses it and how it starts.** The person or system that starts a task, and where (chat, Slack, email, a schedule).
+3. **What each request brings.** The files and facts that arrive with every request, and their formats.
+4. **What the agent always knows.** The standing documents and rules, and which of the owner's documents hold them.
+5. **What it must reach.** The data sources each case needs, and whether the owner can connect them now or fakes will do for a first version.
+6. **The output.** Its format, where it goes, and one real example of a good one, given by the owner or drafted by you and corrected by them.
+7. **The boundary.** What the agent must never do, what it must leave to a person, and when it must stop and ask.
+8. **The cases.** A small, varied set: ordinary work, ambiguity, missing input, partial failure, and a request it should decline.
+9. **Exact values.** The values the agent must use word for word and what it runs on: the author name on each change, the output file name and location, which side it acts for, and the model. Ask for them; never keep a template's model.
+10. **How each case is checked.** A check in code, a person reviewing the result, or left for later. A case judged by a model reading meaning is reviewed by a person until real conversations exist to calibrate a judge.
+
+When an item stays vague after one follow-up, show the owner something concrete instead of asking again: a sample result on their own material, or two contrasting results and "which is closer?".