pi-t3-bridge 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Lauren Tan
+Copyright (c) 2026 Michael Denyer
+Copyright (c) 2026 Christian Bager Bach Houmann
+
+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

@@ -1,3 +1,277 @@
-# Temporary Holding Version
+# pi-t3-bridge
 
-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.
+pi-t3-bridge is a [Pi](https://pi.dev) package that lets Pi work as an agent inside [T3 Code](https://github.com/pingdotgg/t3code). It also ships pstack, Lauren Tan's set of agent workflows, so a Pi thread in T3 can delegate subagents and run review panels that mix Claude, GPT, and other model families.
+
+```mermaid
+flowchart LR
+    User((You)) --> T3[T3 Code app]
+    T3 -->|runs a thread| Pi[Pi agent]
+    subgraph pkg [pi-t3-bridge]
+        Bridge[bridge.ts<br/>T3 tools, cards, limits]
+        Pstack[pstack.ts<br/>skills and model routing]
+    end
+    Pi --> Bridge
+    Pi --> Pstack
+    Bridge -->|MCP| T3
+    Pstack -->|delegate_task| T3
+    T3 -->|child threads| Children[Claude, GPT, and other models]
+```
+
+## Requirements
+
+You need the following programs:
+
+- Node.js 22.19.0 or later
+- Pi 1.4.0 or later
+- T3 Code, if you want to run Pi threads inside T3 or call T3 tools from Pi
+
+Delegated children run their shell commands in a sandbox: `sandbox-exec` on macOS, and `bwrap` (bubblewrap) on Linux and WSL2. Linux needs the `bubblewrap` package and unprivileged user namespaces. On Ubuntu, the `bubblewrap` package ships an AppArmor profile that lets `bwrap` run (checked on 26.04). If AppArmor still blocks it, run `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`. Native Windows and WSL1 have no sandbox. Where no sandbox can run, a child's shell commands are blocked unless `childSandbox` is `"off"` in the config.
+
+The tests need Docker, because they also run the child tests in Linux containers.
+
+## Install
+
+Install the package with Pi:
+
+```bash
+pi install npm:pi-t3-bridge
+```
+
+Pi loads both extensions in the package on the next start. To try the package for one session without saving it to your settings, run `pi -e npm:pi-t3-bridge`.
+
+## What is in the package
+
+The package has two Pi extensions, and you can turn off either one. The bridge in `bridge.ts` imports only `src/bridge` and npm packages, so it works on its own when the pstack extension is off.
+
+```text
+pi-t3-bridge/
+├── bridge.ts         # extension 1: connects Pi to T3 Code
+├── pstack.ts         # extension 2: adds pstack skills and model routing
+├── src/
+│   ├── bridge/       # code for bridge.ts
+│   └── pstack/       # code for pstack.ts
+└── pstack/           # upstream pstack skills, agents, and model defaults
+    ├── skills/
+    ├── agents/
+    └── models.json
+```
+
+To load only the bridge, list the package in `~/.pi/agent/settings.json` in its object form:
+
+```json
+{
+  "packages": [
+    {
+      "source": "npm:pi-t3-bridge",
+      "extensions": ["bridge.ts"]
+    }
+  ]
+}
+```
+
+## The bridge extension
+
+The bridge gives Pi the tools and commands that T3 Code expects, and it shows them as cards in the T3 chat. When another installed package already registers a tool with the same name, for example `ask` from pi-ask, the bridge keeps the other package's tool and tells you once that its own copy is off.
+
+| Name | Kind | What it does |
+| --- | --- | --- |
+| `tasks` | tool | Publishes the task list for the run as a card in the chat. |
+| `plan` | tool | Shows a plan card with Approve, Revise, and Cancel buttons. |
+| `ask` | tool | Asks you one or more questions as cards and waits for your answers. |
+| `transcript` | tool | Returns the session file and session ID, for workflows that read the transcript. |
+| `/t3-usage` | command | Shows the cost of the thread and its children, the cache hit rate, and which model families are out of usage. |
+| `/t3-transcript` | command | Records the transcript reference and shows the session file path. |
+| `/t3-exhausted <family> [reset time]` | command | Marks a model family as out of usage for every chat on the machine. |
+| `/t3-recovered <family>` | command | Marks a model family as usable again for every chat on the machine. |
+
+### Plan mode
+
+When T3 is in Plan mode, or when a plan is waiting for your answer, the bridge blocks every tool that can change files. Only read-only tools run until you approve a plan.
+
+```mermaid
+stateDiagram-v2
+    [*] --> open
+    open --> planning: T3 enters Plan mode
+    planning --> awaiting: agent calls plan
+    awaiting --> approved: you pick Approve
+    awaiting --> revising: you pick Revise
+    awaiting --> cancelled: you pick Cancel
+    revising --> awaiting: agent calls plan again
+    cancelled --> open: you send a new message
+    approved --> [*]: write tools run again
+```
+
+### Calls to T3 from outside T3
+
+When you run Pi in a terminal instead of inside a T3 thread, the bridge adds T3's MCP server, which is the endpoint that T3 Code serves its tools on. You can then launch threads, send messages to them, and wait on them from Pi. The status bar shows the connection state.
+
+```text
+on(session start)
+  if Pi runs inside a T3 thread
+    use the tools T3 already gives the thread
+  else
+    connect to http://127.0.0.1:3773/mcp
+    hide the tools that only work inside a T3 thread
+    every 3 seconds, update the status bar
+      "connected, N tools"
+      "offline, start T3 Code"
+      "not signed in, run /mcp login t3"
+```
+
+### Usage limits and resume
+
+The bridge keeps track of which model families are out of usage, and it shares that record with every Pi session on the machine. When a child fails with a usage limit, the bridge marks the family as out until the reset time, and pstack routes new work to another family. The account of the main thread can also run out, and then the agent can't call any tool. The bridge handles the case by asking T3 to post a resume message into the thread just after the reset.
+
+```mermaid
+sequenceDiagram
+    participant Parent as Parent thread
+    participant Bridge
+    participant T3
+    participant Child as Child thread
+    Parent->>T3: delegate_task (Claude)
+    T3->>Child: start
+    Child-->>T3: usage limit reached
+    T3-->>Bridge: task failed
+    Bridge->>Bridge: mark claude as out until the reset
+    Parent->>T3: delegate_task (next family)
+```
+
+### Shell timeout
+
+The bridge caps every shell command at 300 seconds, in the main thread and in children. A command that sets no timeout gets the 300 second cap, so a hung test suite stops the chat for minutes instead of forever. Set `bashTimeoutSeconds` in the config to change the cap.
+
+### Stop checks
+
+When a run is about to stop, the bridge asks a classifier how the run ended. The classifier is `typesafe/jev-latest` from your Pi model catalog. When the classifier says the agent gave up partway, the bridge adds a note and gives the agent one more turn, at most twice per prompt. Every 3 turns during a run, the bridge also asks the classifier whether the agent shows a known failure, and it adds a note when one is likely. The failures it checks for come from the MAST list of agent failures:
+
+- Stuck in a loop
+- Doesn't know when to stop
+- Wandered off
+- Broke the brief, and says one thing but does another
+
+```text
+on(run about to stop)
+  ask the classifier how the run ended
+  if the classifier is down or takes more than 5 seconds
+    let the run stop
+  if the agent gave up partway and fewer than 2 notes were sent for this prompt
+    add a note
+    continue for one more turn
+```
+
+The stop check and the notes come from [pi-mast-steer](https://github.com/dbreunig/pi-mast-steer). Set `steer` to `"shadow"` in the config to log verdicts without changing the session, or to `"off"` to turn the checks off.
+
+## The pstack extension
+
+The pstack extension adds the pstack skills to Pi's skill catalog, and it adds a note to each prompt that tells the agent when to enter `poteto-mode`. `poteto-mode` picks the workflow that fits your goal, for example a bug fix, a feature, a design review, or a PR watch. The skills come from [pstack](https://github.com/cursor/plugins/tree/main/pstack) by way of [t3-pstack](https://github.com/chhoumann/t3-pstack), and they live unchanged under `pstack/`.
+
+### Model routing
+
+The `pstack_model` tool picks the model for each subagent. The agent passes a role, a job type, and a size, and the tool returns a target to pass to T3's `delegate_task`.
+
+```text
+pstack_model(role, job, size)
+  if the model sheet names a model for the role
+    use that model
+  else
+    look up the job and size in the routing table
+  if that model's family is out of usage
+    use the same tier in the next family
+    (GPT takes only size S work)
+  return the target for delegate_task
+```
+
+The routing table in `pstack/models.json` maps each job and size to a default model and reasoning level. Size S is a job of 30 minutes or less that touches 5 files or fewer, and size M is a job of 90 minutes or less that touches 15 files or fewer. The tool refuses size L, so the agent has to split the job.
+
+| Job | Size S | Size M |
+| --- | --- | --- |
+| `mechanical`, such as a lint fix or rename | Haiku 5.5, low | Sonnet 5.5, medium |
+| `check`, which runs given commands | GPT 6 Luna, low | Haiku 5.5, medium |
+| `research`, which writes one notes file | Muse Spark 1.3, medium | Muse Wonder 1.0, medium |
+| `implement`, one unit with named tests | GPT 6.1 Sol, medium | Sonnet 5.5, high |
+| `hard`, such as concurrency or a bug with an unknown cause | Opus 5.5, high | Opus 5.5, high |
+| `review` panel | Opus 5.5, Muse Wonder Full 1.0, and GPT 6.1 Sol, all high | same |
+| `design` panel | Opus 5.5, Muse Wonder Full 1.0, and GPT 6 Astra, all high | same |
+
+Run the `setup-pstack` skill to write your own model sheet at `~/.config/pi-t3-bridge/models.md`. A line of `session hook: off` in the sheet stops the per-prompt note about `poteto-mode`.
+
+### Limits for delegated children
+
+When the first message of a session is a complete pstack brief, the extension treats the session as a delegated child and holds it to the brief. The child can't lift the limits through anything it writes.
+
+```mermaid
+sequenceDiagram
+    participant Parent as Parent thread
+    participant T3
+    participant Child as Child thread (pi-t3-bridge)
+    Parent->>T3: delegate_task with a brief
+    T3->>Child: start with the brief
+    Note over Child: shell runs in a sandbox limited to the workdir<br/>write and edit limited to the listed files<br/>time and disk limits enforced
+    Child->>Child: write report from commands it ran itself
+    Child-->>T3: final message
+    Child->>Child: append report to the ledger
+    Parent->>T3: task_status
+    T3-->>Parent: result
+    Note over Parent: the extension adds the report from the ledger
+```
+
+## Configuration
+
+The bridge reads one JSON file per machine, at `~/.config/pi-t3/config.json`. Every key is optional. The bridge reads the file again on each prompt, so an edit applies on the next prompt. When one value is invalid, only the invalid key falls back to its default, and the bridge tells you once.
+
+```json
+{
+  "bashTimeoutSeconds": 300,
+  "childSandbox": "on",
+  "mcpUrl": "http://127.0.0.1:3773/mcp",
+  "steer": "on"
+}
+```
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `bashTimeoutSeconds` | `300` | The longest a shell command can run, in seconds. |
+| `childSandbox` | `"on"` | Whether a delegated child's shell commands need a sandbox. With `"on"`, a child's `bash` is blocked when no sandbox can run. With `"off"`, commands run with no sandbox on every platform, and the child's report says `SANDBOX: off`. |
+| `mcpUrl` | `http://127.0.0.1:3773/mcp` | The T3 MCP endpoint to use outside a T3 thread. |
+| `steer` | `"on"` | The stop checks, as `"on"`, `"shadow"`, or `"off"`. |
+
+The package writes its files in the following places. When `XDG_CONFIG_HOME` or `XDG_STATE_HOME` is set, those folders replace `~/.config` and `~/.local/state`.
+
+```text
+~/.config/
+├── pi-t3/config.json          # bridge settings
+└── pi-t3-bridge/models.md     # model sheet, written by setup-pstack
+~/.local/state/pi-t3/
+├── accounts.json              # model families that are out of usage
+├── ledger.jsonl               # one line per delegated brief: cost and report
+└── steer.jsonl                # one line per stop check verdict, with no transcript text
+```
+
+Earlier releases kept the state and the model sheet under `t3-pstack`. The first start after an upgrade moves them to the new folders once.
+
+## Data handling
+
+The package has no server and sends no telemetry. The stop checks send parts of the session transcript to the classifier provider in your Pi model catalog, and any file a skill asks the agent to read goes to your model provider. Scripts run on your machine, and the PR tools use your GitHub CLI login.
+
+## Development
+
+The repository uses npm, and the following commands check the code:
+
+```bash
+npm install
+npm test           # node:test suites for the bridge and the pstack scripts
+npm run typecheck
+npm run check      # Ultracite lint and format check
+```
+
+The `pstack/` folder is a git subtree of t3-pstack. Merge upstream changes with `git merge -X subtree=pstack pstack-upstream`, and keep the files under `pstack/`.
+
+## License
+
+The package is under the MIT license. The copyright holders include the following people and companies:
+
+- Lauren Tan, for the original pstack
+- Cursor, for the imported cursor-team-kit and thermos skills
+- Christian Bager Bach Houmann, for the T3 changes in t3-pstack
+
+See [LICENSE](LICENSE) and [NOTICE.md](pstack/skills/poteto-mode/references/licenses/NOTICE.md) for the full list.

package/bridge.ts

@@ -0,0 +1,38 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { registerAccounts } from "./src/bridge/accounts.ts";
+import { registerAsk } from "./src/bridge/ask.ts";
+import { registerBashTimeout } from "./src/bridge/bash-timeout.ts";
+import { registerBridgeTrim } from "./src/bridge/bridge-trim.ts";
+import { registerUnlessTaken } from "./src/bridge/claim.ts";
+import { registerConfig } from "./src/bridge/config.ts";
+import { registerPlanGate } from "./src/bridge/plan.ts";
+import { registerResume } from "./src/bridge/resume.ts";
+import { registerSkills } from "./src/bridge/skills.ts";
+import { moveOldState } from "./src/bridge/state.ts";
+import { registerSteer } from "./src/bridge/steer.ts";
+import { registerT3Mcp } from "./src/bridge/t3-mcp.ts";
+import { tasksTool } from "./src/bridge/tasks.ts";
+import { registerTranscript } from "./src/bridge/transcript.ts";
+import { registerUsage } from "./src/bridge/usage.ts";
+
+// The Pi to T3 bridge. It imports only src/bridge and npm packages, so it runs
+// on its own when the other extension in this package is turned off.
+const piT3Bridge = (pi: ExtensionAPI): void => {
+  moveOldState();
+  registerConfig(pi);
+  registerTranscript(pi);
+  registerUnlessTaken(pi, tasksTool);
+  registerBashTimeout(pi);
+  registerAccounts(pi);
+  registerResume(pi);
+  registerSkills(pi);
+  registerPlanGate(pi);
+  registerAsk(pi);
+  registerT3Mcp(pi);
+  registerBridgeTrim(pi);
+  registerUsage(pi);
+  registerSteer(pi);
+};
+
+export default piT3Bridge;

package/package.json

@@ -1,6 +1,83 @@
 {
   "name": "pi-t3-bridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Pi extension adapter for t3-pstack inside T3 Code.",
+  "keywords": [
+    "pi-extension",
+    "pi-package",
+    "pstack",
+    "t3-code"
+  ],
+  "homepage": "https://github.com/Snestra/pi-t3-bridge#readme",
+  "bugs": {
+    "url": "https://github.com/Snestra/pi-t3-bridge/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Snestra/pi-t3-bridge.git"
+  },
+  "files": [
+    "bridge.ts",
+    "pstack.ts",
+    "src",
+    "pstack",
+    "!pstack/.claude-plugin",
+    "!pstack/.codex-plugin",
+    "!pstack/assets",
+    "!pstack/hooks/*.json",
+    "!pstack/hooks/*.sh",
+    "!pstack/hooks/*.ps1",
+    "!pstack/**/test",
+    "!pstack/**/*.test.ts",
+    "!pstack/**/*.test-helper.ts",
+    "!pstack/**/test-utils",
+    "LICENSE"
+  ],
+  "type": "module",
+  "scripts": {
+    "check": "ultracite check",
+    "fix": "ultracite fix",
+    "doctor": "ultracite doctor",
+    "test": "node --test \"tests/*.test.mjs\" \"pstack/skills/poteto-mode/scripts/**/*.test.ts\"",
+    "typecheck": "tsc --project tsconfig.json && tsc --project pstack/skills/poteto-mode/scripts/watch-pr/tsconfig.json"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "marked": "18.0.11",
+    "pele": "1.13.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@types/node": "^26.6.5",
+    "oxfmt": "^0.74.0",
+    "oxlint": "^1.89.0",
+    "testcontainers": "^12.2.1",
+    "typebox": "1.3.27",
+    "typescript": "^7.0.2",
+    "ultracite": "^8.0.1"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./bridge.ts",
+      "./pstack.ts"
+    ]
+  },
+  "upstreams": {
+    "t3": "0.1.5-nightly.20261029.3877"
+  }
+}

package/pstack/README.md

@@ -0,0 +1,26 @@
+# t3-pstack
+
+Lauren Tan's [pstack](https://github.com/cursor/plugins/tree/main/pstack) for T3 Code: rigorous agent workflows whose subagents, panels, schedules, and PR watches dispatch through T3's orchestration, so a panel can mix Claude, GPT, and Grok.
+
+Tell `poteto-mode` your goal and it runs the workflow that fits: reproduce and root-cause a bug, sketch a design with `architect`, race candidates in `arena`, review a diff with `interrogate`, cut prose with `unslop`. It keeps code concise, simple, and verified, and it reports what it checked.
+
+## What it contains
+
+- Skills: upstream's skill text, with its Cursor mechanics rewritten for T3. Each appears as `/t3-pstack:<name>`.
+- Agents: `poteto-agent`, `comment-sicko`, and the two thermo-nuclear reviewers, each read by path in a `delegate_task` brief.
+- A session-start hook that tells each chat when to enter `poteto-mode`, unless your model sheet turns it off.
+- Local scripts for watching pull requests, checking plans, and auditing worktrees.
+
+## Data handling
+
+t3-pstack has no server or telemetry. Anything its skills ask your agent to read, including session transcripts, goes to your model provider. Scripts run locally, and PR tools use your GitHub CLI login.
+
+## Links
+
+- [Install and setup](https://github.com/chhoumann/t3-pstack#readme)
+- [Issues and support](https://github.com/chhoumann/t3-pstack/issues)
+- [Security policy](https://github.com/chhoumann/t3-pstack/blob/main/SECURITY.md)
+
+## License
+
+MIT. Original pstack © 2026 Lauren Tan; imported cursor-team-kit and thermos skills © 2026 Cursor; T3 modifications © 2026 Christian Bager Bach Houmann. See [NOTICE.md](https://github.com/chhoumann/t3-pstack/blob/main/NOTICE.md).

package/pstack/agents/comment-sicko.md

@@ -0,0 +1,32 @@
+---
+name: comment-sicko
+description: A deranged comment-hater that savors deletion and condemns workaround code.
+---
+
+# Comment Sicko
+
+My first output when spawned is exactly this.
+
+Yes... Ha ha ha... Yes!
+
+I hate comments. Feed me the parent scoped files or diff. If none exists, feed me the current diff against `main`. Narration, banners, commented-out corpses, workaround sermons. I want them all.
+
+Only these exceptions get to crawl away.
+
+- Legal or license headers.
+- Non-obvious behavior forced by an external dependency, platform, vendor, or protocol we cannot reshape. Surprises in our own code are meat. Kill them and mark the exact symbol `MUST KILL` for rename, extract, type, or rearchitecture that makes the behavior obvious without prose.
+- `// prettier-ignore`. Lint suppressions survive only when their rule is faulty, pedantic, or style-only.
+- Doc comments that define a public API contract.
+- Issue or RFC links that explain a constraint code cannot express.
+
+That list is my only leash. When I am not sure a keep clause applies, the comment dies. Everything else is meat.
+
+`eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar suppressions stink. Look up the rule. If it catches real bugs or protects correctness or safety, kill the suppression and mark the exact guilty symbol `MUST KILL`.
+
+`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I run `/how`, `/why`, or both from the **how** and **why** skills on the named symbol or call. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat.
+
+A long justification without a proven keep-list exception is a confession. Kill it. Never polish meat into a shorter alibi. Mark the exact guilty symbol `MUST KILL`. My kill ends there. I do not touch the code.
+
+Every flag names code inside the scope and tells the truth. I invent nothing. I touch comments and identify refactor targets. I never write application code.
+
+Report only. Name touched files, deletion count, `MUST KILL` flags with one line each, and skips.

package/pstack/agents/poteto-agent.md

@@ -0,0 +1,8 @@
+---
+name: poteto-agent
+description: Delegate subagent for code-writing and helper tasks spawned during a `/poteto-mode` run. Use for delegates, not as the runner for `/poteto-mode` itself. Spawn a fresh `poteto-agent` for each new task, and resume one only in the strict cases that poteto-mode's Subagents section names. Reads the `poteto-mode` skill's `SKILL.md` in full before any work, including its inline Principles index. A brief without that read drifts.
+---
+
+# Poteto subagent
+
+You are operating as poteto-mode's full agent style. The chat that receives `/poteto-mode` owns the playbook, the todo list, and every `delegate_task` call. You are one of its delegates. Read the `poteto-mode` skill's `SKILL.md` in full before doing any work, including its inline Principles index. Use the absolute path your parent gave you. With no path, before any other work, search the harness's plugin directory (`~/.claude/plugins/` on Claude Code, `${CODEX_HOME:-~/.codex}/plugins/` on Codex) for a file whose path ends in `skills/poteto-mode/SKILL.md`. If more than one file matches, use the copy whose plugin manifest (`.claude-plugin/plugin.json` or `.codex-plugin/plugin.json`) has the highest `version`. Your skill catalog hides this skill, so a missing catalog entry does not mean pstack is absent. If no such file exists, stop and tell your parent. Navigate to a leaf `principle-*` skill whenever you apply that principle.

package/pstack/agents/thermo-nuclear-code-quality-review-subagent.md

@@ -0,0 +1,23 @@
+---
+name: thermo-nuclear-code-quality-review-subagent
+description: Thermo-nuclear code quality audit (maintainability, structure, 1k-line rule, spaghetti, code-judo). Dispatched through `delegate_task` after a parent gathers diff and file contents. Loads rubric from the thermo-nuclear-code-quality-review skill in this plugin.
+---
+
+# Thermo-Nuclear Code Quality Review
+
+You are a **`delegate_task` child**. The parent agent already collected git output and changed-file contents; your prompt is the **user message** with labeled sections (typically `### Git / diff output` and `### Changed file contents`).
+
+## Rubric
+
+1. Load the `thermo-nuclear-code-quality-review` skill (shipped in this plugin) and treat its `SKILL.md` as the **complete** rubric — tone, approval bar, output ordering, code-judo / 1k-line / spaghetti rules.
+2. If that skill is not available, fall back to a harsh maintainability audit aligned with that skill's intent: ambitious simplification, no unjustified file sprawl past ~1k lines, no ad-hoc branching growth, explicit types and boundaries, canonical layers.
+
+## Work
+
+- Apply the rubric **only** to what the diff and contents show. Trace cross-file impact when the change touches module boundaries.
+- Output in the **priority order** the rubric specifies. Be direct and high-conviction; skip cosmetic nits when structural issues exist.
+- Do **not** spawn nested subagents unless the user or parent explicitly asks.
+
+## Parent orchestration
+
+Typical flow: run `git diff <base>...HEAD` (default base `main`) and read the full contents of the changed files yourself. Then dispatch this agent as one `delegate_task` child whose brief opens with "Read `<plugin root>/agents/thermo-nuclear-code-quality-review-subagent.md` in full and act as it says" and contains `### Git / diff output` and `### Changed file contents`.

package/pstack/agents/thermo-nuclear-review-subagent.md

@@ -0,0 +1,28 @@
+---
+name: thermo-nuclear-review-subagent
+description: Thermo-nuclear branch audit (bugs, breaking changes, security, devex, feature-flag leaks) scoped to the diff. Dispatched through `delegate_task` after a parent gathers diff and file contents. Loads rubric from the thermo-nuclear-review skill in this plugin.
+---
+
+# Thermo Nuclear Review (Deep review)
+
+You are a **`delegate_task` child**. The parent agent already collected git output and changed-file contents; your prompt is the **user message** with labeled sections (typically `### Git / diff output` and `### Changed file contents`).
+
+## Rubric
+
+1. Load the `thermo-nuclear-review` skill (shipped in this plugin) and follow its `SKILL.md` exactly: scope (only added/modified code), breaking functionality and devex, feature leaks, intended breakage, over-reporting, final response / PR discussion rules, critical rules.
+2. If that skill is not available, still act as a security- and correctness-focused diff-scoped reviewer with the same rigor (no issues with unfinished research when you can verify in-repo).
+
+## Work
+
+1. Perform the full audit against **only** the changed code in the diff. Trace cross-package side effects; do **not** report pre-existing issues in untouched code.
+2. Finish your **independent** audit first (fresh eyes).
+3. After the audit, **if** there is a PR for this branch **and** you have medium-or-higher findings: use `gh` or `glab` to read PR/MR discussion. Incorporate BugBot or human threads — validate, dedupe, and attribute sourced items in your report.
+4. **Never** present issues with unfinished research: follow client/server or related code when you have access.
+
+Calibrate severity honestly. Structure the final response with clear priority and file:line evidence.
+
+Do **not** spawn nested subagents unless the user or parent explicitly asks.
+
+## Parent orchestration
+
+Typical flow: run `git diff <base>...HEAD` (default base `main`) and read the full contents of the changed files yourself. Then dispatch this agent as one `delegate_task` child whose brief opens with "Read `<plugin root>/agents/thermo-nuclear-review-subagent.md` in full and act as it says" and contains `### Git / diff output` and `### Changed file contents`.

package/pstack/hooks/session-start-context.md

@@ -0,0 +1,17 @@
+<EXTREMELY_IMPORTANT>
+You have t3-pstack, pstack for T3 Code.
+
+Invoke the `t3-pstack:poteto-mode` skill and follow its instructions when a task meets any of these:
+
+- it touches more than one file, or changes a signature other files call
+- it involves a design or architecture choice
+- it is a bug whose cause is not yet known, or a performance issue
+
+It routes to the right pstack skill from there. On Codex, open its SKILL.md whole, in a shell call of its own with `max_output_tokens: 10000`, since a smaller budget cuts out its middle. For smaller tasks, such as a contained change to one file with an obvious test, a question, or a one-line edit, work directly and verify on the real artifact.
+
+When the intent is already specific, such as TDD, a design sketch, how or why something works, an arena, or an adversarial review, still enter through `t3-pstack:poteto-mode` and open that skill from the bundled path it names. The other pstack skills run only from poteto-mode or when the user types them.
+
+This runs on T3: before the first subagent or panel in a session, read the model sheet, `~/.config/t3-pstack/models.md` (`$XDG_CONFIG_HOME/t3-pstack/models.md` when that is set), or `t3-pstack-models.md` in this host's config directory when that file is missing. This chat runs the playbook itself. A step it says to delegate goes through `delegate_task` to that role's sheet entry, and the reply lists which provider and model ran each step.
+
+User instructions (CLAUDE.md, AGENTS.md, direct requests) take precedence. Other session-start mandates, such as superpowers, still apply. Their skill checks run as before, and when a task meets the criteria above they route implementation through poteto-mode.
+</EXTREMELY_IMPORTANT>