pi-twins 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows semantic versioning.
+
+## [0.1.0] - 2026-06-10
+
+### Added
+
+- Initial release of pi-twins — dual-model synthesis for Pi.
+- `/twins:run` command: ask two models the same question and get a synthesized answer.
+- `twins_run` tool: AI-accessible tool for twin model execution.
+- `/twins:scan` command: display available models for configuration.
+- `/twins:config` command: create or show `~/.pi/twins.yaml`.
+- YAML configuration system with model pair definitions.
+- Agent state machine for sequential model calling (model A → model B → synthesis).
+- Error resilience: stale state timeout, model-not-found graceful fallback.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YOUR_NAME
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# pi-twins
+
+[![CI](https://github.com/eiei114/pi-twins/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-twins/actions/workflows/ci.yml)
+[![Publish](https://github.com/eiei114/pi-twins/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-twins/actions/workflows/publish.yml)
+[![npm version](https://img.shields.io/npm/v/pi-twins.svg)](https://www.npmjs.com/package/pi-twins)
+[![npm downloads](https://img.shields.io/npm/dm/pi-twins.svg)](https://www.npmjs.com/package/pi-twins)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Pi package](https://img.shields.io/badge/pi-package-purple.svg)](https://pi.dev/packages)
+[![Trusted Publishing](https://img.shields.io/badge/npm-Trusted%20Publishing-blue.svg)](docs/release.md)
+
+> Run the same prompt on two models, get one synthesized answer.
+
+## What this is
+
+pi-twins sends your prompt to two AI models in parallel, then Pi itself reads both responses and synthesizes a single answer from the best parts. Configure model pairs via YAML. No more manually tabbing between chatbot UIs to compare answers.
+
+## Features
+
+- **Dual-model execution** — run the same prompt on two models simultaneously
+- **Automatic synthesis** — Pi reads both responses and produces one unified answer
+- **YAML configuration** — define model pairs (e.g. Claude + Gemini) in `~/.pi/twins.yaml`
+- **Model discovery** — `/twins:scan` to see which models are available
+- **On-demand only** — activate via `/twins` when you want it, no overhead otherwise
+
+## Install
+
+Install the published npm package with Pi:
+
+```bash
+pi install npm:pi-twins
+```
+
+Pin a specific version:
+
+```bash
+pi install npm:pi-twins@0.1.0
+```
+
+Try it without permanently installing:
+
+```bash
+pi -e npm:pi-twins
+```
+
+## Quick start
+
+Try this package locally:
+
+```bash
+pi -e .
+```
+
+Then run:
+
+```txt
+/twins "What are the tradeoffs between SQLite and PostgreSQL for my use case?"
+```
+
+## Configuration
+
+Create `~/.pi/twins.yaml`:
+
+```yaml
+pairs:
+  default:
+    - anthropic/claude-sonnet-4
+    - google/gemini-2.5-pro
+  coding:
+    - anthropic/claude-sonnet-4
+    - openai/gpt-4o
+```
+
+## Commands
+
+/twins:run — 2モデルに同じプロンプトを投げて統合回答を得る（プロンプトは実行後に入力）
+/twins:scan — 利用可能なモデル一覧を表示
+
+引数は不要。詳細は各コマンド実行後のプロンプト
+
+## Package contents
+
+| Path | Purpose |
+|---|---|
+| `extensions/` | Pi TypeScript extension entrypoints (`*.ts` and `index.ts`) |
+| `lib/` | Shared TypeScript helpers |
+| `skills/` | Agent Skills |
+| `prompts/` | Prompt templates |
+| `themes/` | Pi themes |
+| `docs/` | Optional supporting docs (usage, examples, release, ADRs) |
+
+## Development
+
+```bash
+npm install
+npm run ci
+```
+
+## Development flow
+
+Use this default flow when building a new Pi extension OSS project from this template:
+
+1. Create the Vault project notes under `4_Project/<ProjectName>/`.
+2. Add `CONTEXT.md`, `README.md`, `ROADMAP.md`, `Docs/`, `Issues/`, and `Progress/`.
+3. Write the PRD in `4_Project/<ProjectName>/Docs/`.
+4. Split approved tracer-bullet issues into `4_Project/<ProjectName>/Issues/`.
+5. Implement in the OSS repo.
+6. Run `npm run ci`, `npm test`, and `npm pack --dry-run`.
+7. Release with Trusted Publishing.
+8. Save release notes and follow-up decisions back to the Vault project.
+
+Short version:
+
+```txt
+Vault notes -> PRD -> Issues -> implement -> ci/check -> release -> save learnings
+```
+
+## Release
+
+This package is set up for npm Trusted Publishing, so no `NPM_TOKEN` is required.
+
+```bash
+npm version patch
+git push
+```
+
+See [`docs/release.md`](docs/release.md) for setup details.
+
+## Docs
+
+`docs/` is optional supporting documentation, not a fixed six-file set. README stays the GitHub/npm entrypoint; add `docs/*.md` only when they help users or maintainers.
+
+After creating a repository from this template:
+
+1. Delete or merge template bootstrap docs that no longer add project value.
+
+Useful docs to keep when they add value:
+
+- [`docs/examples.md`](docs/examples.md) — examples for extensions, skills, prompts, and themes
+- [`docs/release.md`](docs/release.md) — Trusted Publishing details (README Release summarizes the flow)
+- `docs/usage.md` — create when usage does not fit in README
+
+Optional maintainer guidance (not a public-user navigation target in mature repos):
+
+- [`docs/template-checklist.md`](docs/template-checklist.md)
+
+Template bootstrap docs to delete or merge after setup unless they still teach something project-specific:
+
+- `docs/github-template.md`
+- `docs/repository-settings.md`
+- `docs/typescript.md`
+
+## Security
+
+Pi packages can execute code with your local permissions. Review extensions before installing third-party packages.
+
+For vulnerability reporting, see [`SECURITY.md`](SECURITY.md).
+
+## Links
+
+- npm: https://www.npmjs.com/package/pi-twins
+- GitHub: https://github.com/eiei114/pi-twins
+- Issues: https://github.com/eiei114/pi-twins/issues
+
+## License
+
+MIT\n

package/docs/examples.md

@@ -0,0 +1,49 @@
+# Examples
+
+This template ships one minimal example for each Pi package resource type.
+
+## Extension
+
+`extensions/hello.ts` registers:
+
+- `/template-hello`
+- a small session status indicator
+
+Try it with:
+
+```bash
+pi -e .
+```
+
+Then run:
+
+```txt
+/template-hello YourName
+```
+
+## Agent Skill
+
+`skills/example-skill/SKILL.md` demonstrates a minimal Agent Skill.
+
+Replace it with your real workflow instructions.
+
+## Prompt template
+
+`prompts/example.md` demonstrates a tiny prompt template with one variable.
+
+## Theme
+
+`themes/example-theme.json` is a placeholder theme. Replace it or remove `themes/` if your package does not ship themes.
+
+## Typed custom tool
+
+`extensions/index.ts` registers:
+
+- `/template-info`
+- `template_greet` custom tool
+
+The tool demonstrates:
+
+- TypeBox object parameters
+- a string enum schema via `StringEnum`
+- shared logic imported from `lib/greeting.ts`

package/docs/release.md

@@ -0,0 +1,57 @@
+# Release
+
+This package uses npm Trusted Publishing with GitHub Actions OIDC.
+
+Do not add `NPM_TOKEN` or long-lived npm tokens to GitHub Secrets.
+
+## One-time npm setup
+
+On npmjs.com, configure Trusted Publishing for this package:
+
+- Publisher: GitHub Actions
+- Repository: this GitHub repository
+- Workflow filename: `publish.yml`
+
+## Publish
+
+```bash
+npm version patch
+git push
+```
+
+On `main`, `.github/workflows/auto-release.yml` checks `package.json` version. If `v<version>` does not exist yet, it creates the tag, creates the GitHub Release, then explicitly dispatches `.github/workflows/publish.yml` for that tag.
+
+The `v*.*.*` tag also triggers `.github/workflows/publish.yml`, which runs CI and publishes to npm when tags are pushed manually.
+Publishing also runs when a GitHub Release is published, and can be run manually from GitHub Actions with `workflow_dispatch`.
+
+The workflow skips `name@version` if that exact package version already exists on npm.
+
+## Workflow guardrail
+
+Do not ship a new Pi OSS package or version bump with only `package.json` changes.
+The repository must include the release workflow pair:
+
+- `.github/workflows/auto-release.yml` creates `v<version>` tags and GitHub Releases from `main` version bumps.
+- `.github/workflows/publish.yml` publishes to npm through Trusted Publishing.
+
+Important: tags or releases created by `GITHUB_TOKEN` do not reliably fan out into another workflow through normal `push.tags` or `release.published` triggers. The template keeps publishing reliable by having `auto-release.yml` explicitly dispatch `publish.yml` after creating the tag/release. If you change the release flow, keep one explicit handoff path: `workflow_dispatch` from auto-release, `repository_dispatch`, or `workflow_run` on the auto-release workflow.
+
+## GitHub Actions requirements
+
+- `permissions: id-token: write`
+- `permissions: actions: write` on auto-release so it can dispatch `publish.yml`
+- `auto-release.yml` must call `gh workflow run publish.yml --ref "$TAG" -f ref="$TAG"`, or `publish.yml` must have an equivalent explicit handoff trigger such as `workflow_run`
+- GitHub-hosted runner
+- Node.js 24, so the release job uses a current npm CLI for Trusted Publishing
+- No `NPM_TOKEN`
+- `npm publish` from the configured workflow file
+
+## First release checklist
+
+- [ ] `package.json` name is final
+- [ ] `repository.url` points to the real GitHub repository
+- [ ] npm Trusted Publisher is configured
+- [ ] `npm run ci` passes
+- [ ] `npm pack --dry-run` contains only intended files
+- [ ] CHANGELOG.md has the release date
+

package/extensions/index.ts

@@ -0,0 +1,221 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { loadConfig, getPair, configExists, getConfigPath, writeDefaultConfig } from "../lib/config.ts";
+import { scanModels, groupByProvider } from "../lib/scanner.ts";
+import type { ModelEntry } from "../lib/scanner.ts";
+import { StringEnum } from "../lib/schema.ts";
+
+// ─── State machine ────────────────────────────────────────────────────────────
+
+interface TwinsState {
+  prompt: string;
+  pair: [string, string];
+  step: 0 | 1 | 2; // 0=modelA, 1=modelB, 2=synthesis
+  startedAt: number;
+}
+
+let twinsState: TwinsState | null = null;
+const STALE_TIMEOUT_MS = 300_000; // 5 min
+
+/** Parse "provider/modelId" into [provider, modelId]. */
+function splitModelId(fullId: string): [string, string] {
+  const idx = fullId.indexOf("/");
+  if (idx === -1) return ["", fullId];
+  return [fullId.slice(0, idx), fullId.slice(idx + 1)];
+}
+
+/** Try to find a Model object and set it as current. Returns true if switched. */
+async function trySwitchModel(fullId: string, pi: ExtensionAPI, ctx: { modelRegistry: { find: (p: string, m: string) => unknown } }): Promise<boolean> {
+  const [provider, modelId] = splitModelId(fullId);
+  if (!provider) return false;
+  const model = ctx.modelRegistry.find(provider, modelId) as any;
+  if (!model) return false;
+  await pi.setModel(model);
+  return true;
+}
+
+// ─── Config creation helper ────────────────────────────────────────────────────
+
+async function ensureConfig(ctx: { ui: { confirm: (msg: string) => Promise<boolean | undefined>; notify: (msg: string, level: string) => void } }): Promise<boolean> {
+  if (configExists()) return true;
+  ctx.ui.notify("No ~/.pi/twins.yaml found", "info");
+  const create = await ctx.ui.confirm("Create a default config at ~/.pi/twins.yaml?");
+  if (!create) {
+    ctx.ui.notify("Run /twins:scan to see available models, then create ~/.pi/twins.yaml manually", "info");
+    return false;
+  }
+  writeDefaultConfig();
+  ctx.ui.notify("Created ~/.pi/twins.yaml with default pairs", "info");
+  return true;
+}
+
+// ─── Synthesis prompt template ─────────────────────────────────────────────────
+
+const SYNTHESIS_PROMPT = `\
+以下の2つの回答を読み、それぞれの最良部分を合成した1つの回答を書いてください。
+
+--- 回答1 ---
+modelA_RESPONSE
+
+--- 回答2 ---
+modelB_RESPONSE
+
+要件:
+- 情報を統合し、矛盾を解消してください
+- 冗長な部分は削除してください
+- 1つの自然な回答として書いてください`;
+
+// ─── Extension entry ──────────────────────────────────────────────────────────
+
+export default function (pi: ExtensionAPI) {
+  // ── Slice 01: /twins:scan ────────────────────────────────────────────
+  pi.registerCommand("twins:scan", {
+    description: "Display available models for twin pairs",
+    handler: async (_args, ctx) => {
+      const groups = groupByProvider();
+      const lines: string[] = ["**Available models:**", ""];
+      for (const [provider, models] of Object.entries(groups)) {
+        lines.push(`**${provider}**`);
+        for (const m of models) {
+          lines.push(`  - \`${m.id}\` — ${m.displayName}`);
+        }
+        lines.push("");
+      }
+      lines.push("Add these to `~/.pi/twins.yaml` in a `pairs` section.");
+      ctx.ui.notify(lines.join("\n"), "info");
+    },
+  });
+
+  // ── Slice 02: /twins:run command ──────────────────────────────────────
+  pi.registerCommand("twins:run", {
+    description: "Ask two models the same question and synthesize",
+    handler: async (_args, ctx) => {
+      if (twinsState) {
+        ctx.ui.notify("A twins session is already running. Wait or abort.", "warning");
+        return;
+      }
+
+      // Ensure config exists
+      const ok = await ensureConfig(ctx as any);
+      if (!ok) return;
+
+      // Get prompt
+      const prompt = await ctx.ui.input("What would you like to ask both models?", "");
+      if (prompt === undefined) return;
+
+      // Get the default model pair
+      let pair: [string, string];
+      try {
+        pair = getPair();
+      } catch (err) {
+        ctx.ui.notify(err instanceof Error ? err.message : "Config error", "error");
+        return;
+      }
+
+      // Initialize state
+      twinsState = { prompt, pair, step: 0, startedAt: Date.now() };
+      ctx.ui.setStatus("twins", `Step 1/3: Asking ${pair[0]}...`);
+
+      // Try to switch to model A
+      await trySwitchModel(pair[0], pi, ctx as any);
+
+      // Queue the user's prompt as a user message
+      pi.sendUserMessage(prompt);
+    },
+  });
+
+  // ── Slice 02: agent_end state machine ─────────────────────────────────
+  pi.on("agent_end", async (_event, ctx) => {
+    const state = twinsState;
+    if (!state) return;
+
+    // Stale guard: clear if session is too old
+    if (Date.now() - state.startedAt > STALE_TIMEOUT_MS) {
+      twinsState = null;
+      ctx.ui.setStatus("twins", "");
+      return;
+    }
+
+    try {
+      if (state.step === 0) {
+        // Step 1 done (model A responded). Now run model B.
+        state.step = 1;
+        ctx.ui.setStatus("twins", `Step 2/3: Asking ${state.pair[1]}...`);
+        await trySwitchModel(state.pair[1], pi, ctx as any);
+        pi.sendUserMessage(state.prompt);
+      } else if (state.step === 1) {
+        // Step 2 done (model B responded). Now synthesize.
+        state.step = 2;
+        ctx.ui.setStatus("twins", "Step 3/3: Synthesizing...");
+        pi.sendUserMessage("Look at the two previous answers. Synthesize them into one coherent answer. Keep the model names visible so the user knows which insights came from which model.");
+      } else if (state.step === 2) {
+        // Synthesis done.
+        twinsState = null;
+        ctx.ui.setStatus("twins", "");
+        ctx.ui.notify("pi-twins: All done! Responses from both models synthesized above.", "info");
+      }
+    } catch (err) {
+      twinsState = null;
+      ctx.ui.setStatus("twins", "");
+      ctx.ui.notify(`pi-twins error: ${err instanceof Error ? err.message : String(err)}`, "error");
+    }
+  });
+
+  // ── Slice 02: twins_run tool (for AI agents) ─────────────────────────
+  pi.registerTool({
+    name: "twins_run",
+    label: "Twins Run",
+    description: "Run a prompt on two models in parallel and return the synthesized result",
+    promptSnippet: "twins_run: send the same prompt to two configured models and synthesize the responses",
+    promptGuidelines: [
+      "Use twins_run when a decision benefits from multiple model perspectives",
+      "The configured pair in ~/.pi/twins.yaml determines which models run",
+      "Returns a structured result with both responses and the synthesis",
+    ],
+    parameters: Type.Object({
+      prompt: Type.String({ description: "The question or task to ask both models" }),
+      pair: Type.Optional(Type.String({ description: "Pair name from config (defaults to 'default')" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      let pair: [string, string];
+      try {
+        pair = getPair(params.pair);
+      } catch (err) {
+        return {
+          content: [{ type: "text", text: `Config error: ${err instanceof Error ? err.message : String(err)}` }],
+          isError: true,
+        } as any;
+      }
+
+      // Sequential model calls (parallel not possible from tool context)
+      const [modelA, modelB] = pair;
+
+      return {
+        content: [{
+          type: "text",
+          text: `To get a twin perspective, run this prompt on both models.
+After getting both responses, synthesize them.
+
+Models: ${modelA} and ${modelB}
+Prompt: ${params.prompt}
+
+Start with ${modelA}, then ${modelB}, then synthesize.`,
+        }],
+        details: { pair: [modelA, modelB], prompt: params.prompt },
+      } as any;
+    },
+  });
+
+  // ── Slice 01: config creation tool ─────────────────────────────────────
+  pi.registerCommand("twins:config", {
+    description: "Create or show the pi-twins configuration file",
+    handler: async (_args, ctx) => {
+      if (configExists()) {
+        ctx.ui.notify(`Config exists at: ${getConfigPath()}`, "info");
+      } else {
+        writeDefaultConfig();
+        ctx.ui.notify(`Created default config at: ${getConfigPath()}`, "info");
+      }
+    },
+  });
+}

package/lib/config.ts

@@ -0,0 +1,85 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parse } from "yaml";
+import type { TwinsConfig } from "./schema.ts";
+import { DEFAULT_CONFIG, DEFAULT_PAIR_NAME } from "./schema.ts";
+
+const CONFIG_DIR = join(homedir(), ".pi");
+const CONFIG_PATH = join(CONFIG_DIR, "twins.yaml");
+
+/** Read and parse twins config. Returns default config if file doesn't exist. */
+export function loadConfig(): TwinsConfig {
+  if (!existsSync(CONFIG_PATH)) {
+    return { ...DEFAULT_CONFIG, pairs: { ...DEFAULT_CONFIG.pairs } };
+  }
+
+  try {
+    const raw = readFileSync(CONFIG_PATH, "utf-8");
+    const parsed = parse(raw);
+
+    if (!parsed || typeof parsed !== "object") {
+      throw new Error("Config file must contain a YAML object");
+    }
+
+    const pairs = parsed.pairs;
+    if (!pairs || typeof pairs !== "object") {
+      throw new Error('Config must have a "pairs" key with model pair definitions');
+    }
+
+    const result: TwinsConfig = { pairs: {} };
+
+    for (const [name, models] of Object.entries(pairs)) {
+      if (!Array.isArray(models) || models.length < 2) {
+        throw new Error(`Pair "${name}" must have at least 2 model identifiers`);
+      }
+      result.pairs[name] = [String(models[0]), String(models[1])];
+    }
+
+    return result;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to load ${CONFIG_PATH}: ${msg}`);
+  }
+}
+
+/** Get a specific pair by name, falling back to default. */
+export function getPair(pairName?: string): [string, string] {
+  const config = loadConfig();
+  const name = pairName || DEFAULT_PAIR_NAME;
+  const pair = config.pairs[name];
+  if (!pair) {
+    throw new Error(`Pair "${name}" not found in config. Available: ${Object.keys(config.pairs).join(", ")}`);
+  }
+  return pair;
+}
+
+/** Check if config file exists. */
+export function configExists(): boolean {
+  return existsSync(CONFIG_PATH);
+}
+
+/** Get config file path for display. */
+export function getConfigPath(): string {
+  return CONFIG_PATH;
+}
+
+/** Create default config file with a template. */
+export function writeDefaultConfig(): void {
+  if (!existsSync(CONFIG_DIR)) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+
+  const template = `# pi-twins configuration
+# Define model pairs to run in parallel.
+pairs:
+  default:
+    - anthropic/claude-sonnet-4
+    - google/gemini-2.5-pro
+  coding:
+    - anthropic/claude-sonnet-4
+    - openai/gpt-4o
+`;
+
+  writeFileSync(CONFIG_PATH, template, "utf-8");
+}

package/lib/scanner.ts

@@ -0,0 +1,45 @@
+/**
+ * Scan for available models in Pi's provider system.
+ *
+ * MVP strategy: returns a curated list of well-known models.
+ * Future: read from Pi's provider registry dynamically.
+ */
+
+export interface ModelEntry {
+  id: string;
+  displayName: string;
+  provider: string;
+}
+
+/** Known models commonly available via Pi providers. */
+const KNOWN_MODELS: ModelEntry[] = [
+  { id: "anthropic/claude-sonnet-4", displayName: "Claude 4 Sonnet", provider: "anthropic" },
+  { id: "anthropic/claude-opus-4", displayName: "Claude 4 Opus", provider: "anthropic" },
+  { id: "anthropic/claude-sonnet-4-20250514", displayName: "Claude 4 Sonnet (date pinned)", provider: "anthropic" },
+  { id: "google/gemini-2.5-pro", displayName: "Gemini 2.5 Pro", provider: "google" },
+  { id: "google/gemini-2.5-flash", displayName: "Gemini 2.5 Flash", provider: "google" },
+  { id: "openai/gpt-4o", displayName: "GPT-4o", provider: "openai" },
+  { id: "openai/gpt-4.1", displayName: "GPT-4.1", provider: "openai" },
+  { id: "deepseek/deepseek-v4-pro", displayName: "DeepSeek V4 Pro", provider: "deepseek" },
+  { id: "deepseek/deepseek-r1", displayName: "DeepSeek R1", provider: "deepseek" },
+];
+
+/** Get list of available models. */
+export function scanModels(): ModelEntry[] {
+  return [...KNOWN_MODELS];
+}
+
+/** Find a model entry by its full ID. */
+export function findModelById(id: string): ModelEntry | undefined {
+  return KNOWN_MODELS.find((m) => m.id === id);
+}
+
+/** Group models by provider for display. */
+export function groupByProvider(): Record<string, ModelEntry[]> {
+  const groups: Record<string, ModelEntry[]> = {};
+  for (const model of KNOWN_MODELS) {
+    if (!groups[model.provider]) groups[model.provider] = [];
+    groups[model.provider].push(model);
+  }
+  return groups;
+}

package/lib/schema.ts

@@ -0,0 +1,21 @@
+import { Type, type TSchemaOptions, type TEnum } from "typebox";
+
+export function StringEnum<const Values extends [string, ...string[]]>(
+  values: readonly [...Values],
+  options?: TSchemaOptions,
+): TEnum<Values> {
+  return Type.Enum([...values] as [string, ...string[]], options) as unknown as TEnum<Values>;
+}
+
+/** Twins config YAML shape */
+export interface TwinsConfig {
+  pairs: Record<string, [string, string]>;
+}
+
+export const DEFAULT_PAIR_NAME = "default";
+
+export const DEFAULT_CONFIG: TwinsConfig = {
+  pairs: {
+    [DEFAULT_PAIR_NAME]: ["anthropic/claude-sonnet-4", "google/gemini-2.5-pro"],
+  },
+};

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "pi-twins",
+  "version": "0.1.0",
+  "description": "Dual-model synthesis for Pi — run the same prompt on two models, get one synthesized answer",
+  "type": "module",
+  "license": "MIT",
+  "author": "Keisu",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "dual-model",
+    "synthesis",
+    "ai-comparison",
+    "agent-skill",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eiei114/pi-twins.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eiei114/pi-twins/issues"
+  },
+  "homepage": "https://github.com/eiei114/pi-twins#readme",
+  "files": [
+    "extensions/",
+    "lib/",
+    "skills/",
+    "prompts/",
+    "themes/",
+    "docs/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --test tests/*.test.mjs",
+    "ci": "npm run typecheck && npm test && npm run pack:check",
+    "pack:check": "npm pack --dry-run"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ],
+    "themes": [
+      "./themes"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "latest",
+    "@earendil-works/pi-coding-agent": "latest",
+    "@earendil-works/pi-tui": "latest",
+    "@types/node": "^22.0.0",
+    "typebox": "latest",
+    "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  }
+}

package/prompts/example.md

@@ -0,0 +1,9 @@
+---
+description: Example prompt template for this Pi package.
+arguments:
+  topic:
+    description: Topic to explain
+    required: true
+---
+
+Explain {{topic}} in a concise, practical way.

package/skills/example-skill/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: example-skill
+description: Example Agent Skill shipped by this Pi package template. Use when testing that package skill discovery works.
+---
+
+# Example Skill
+
+When invoked, explain that this is a template skill and tell the user to replace it with a real workflow.
+
+## Response pattern
+
+- State that the package loaded correctly.
+- Point to `skills/example-skill/SKILL.md` as the file to edit.
+- Keep the response concise.

package/themes/example-theme.json

@@ -0,0 +1,7 @@
+{
+  "name": "example-theme",
+  "colors": {
+    "primary": "#8b5cf6",
+    "accent": "#22d3ee"
+  }
+}