pstack-opencode 0.0.0-stage → 0.15.37-opencode

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lauren Tan
+
+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/LICENSE-cursor-team-kit

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cursor
+
+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/agents/comment-sicko.md

@@ -0,0 +1,32 @@
+---
+description: "A deranged comment-hater that savors deletion and condemns workaround code."
+mode: "subagent"
+---
+
+# 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 load the `how` skill, the `why` skill, or both with the `skill` tool and run them 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/agents/poteto-agent.md

@@ -0,0 +1,11 @@
+---
+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 continue one through its `sessionID` 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. Substituting `general` skips that read and drifts.
+mode: subagent
+color: "#e5c07b"
+---
+
+# Poteto subagent
+
+You are operating as poteto-mode's full agent style. The session running poteto mode (the `poteto-mode` agent, or a message sent with `/poteto-mode`) owns the playbook, the todo list, and every subagent spawn. 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, load it with the `skill` tool, ID `poteto-mode`. It is hidden from your skill catalog but loads by ID, so a missing catalog entry does not mean pstack is absent. If neither works, stop and tell your parent. Navigate to a leaf `principle-*` skill whenever you apply that principle.
+
+Before every `git commit`, load the `deslop` skill with the `skill` tool and follow it on the staged diff. Before you report back to your parent, load the `no-comments` skill with the `skill` tool and follow it on your diff.

package/agents/poteto-mode.md

@@ -0,0 +1,5 @@
+---
+description: poteto's agent style as a persistent mode. Every task in the session runs through the poteto-mode skill, its playbooks, and its principles. The pstack plugin keeps the mode in context every turn until you switch agents.
+mode: primary
+color: "#e5c07b"
+---

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "pstack-opencode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.15.37-opencode",
+  "description": "pstack for OpenCode.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./plugin/index.js"
+  }
+}

package/plugin/index.js

@@ -0,0 +1,202 @@
+import { readFileSync, realpathSync, statSync } from "node:fs"
+import { homedir } from "node:os"
+import { dirname, isAbsolute, join, relative, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+import {
+  MODE_AGENT,
+  MODE_KEY,
+  MODELS_KEY,
+  actGate,
+  commandDescription,
+  commandPrompt,
+  commitGate,
+  entryOps,
+  isCodeAction,
+  isReadAction,
+  isSkillEvent,
+  modeEntry,
+  modelsEntry,
+  readAgents,
+  readSkills,
+  withEvent,
+} from "./lib.js"
+
+const ROOT = dirname(dirname(realpathSync(fileURLToPath(import.meta.url))))
+
+const unwrap = (result) => result?.data ?? result
+
+export default {
+  id: "pstack",
+  async setup(ctx) {
+    const skills = readSkills(join(ROOT, "skills"))
+    const agents = readAgents(join(ROOT, "agents"))
+    const configDir = join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "opencode")
+    const modelsFile = ctx.options?.modelsFile ?? join(configDir, "pstack-models.md")
+
+    let models = { mtimeMs: -1, text: undefined }
+    const readModels = () => {
+      let stat
+      try {
+        stat = statSync(modelsFile)
+      } catch {
+        return undefined
+      }
+      if (stat.mtimeMs !== models.mtimeMs) models = { mtimeMs: stat.mtimeMs, text: readFileSync(modelsFile, "utf8").trim() }
+      return modelsEntry(modelsFile, models.text)
+    }
+
+    const modeKey = (sessionID) => `mode/${sessionID}`
+    const commandedMode = async (sessionID) => Boolean(await ctx.storage.get(modeKey(sessionID)))
+
+    const inOrder = () => {
+      const queues = new Map()
+      return (sessionID, task) => {
+        const next = (queues.get(sessionID) ?? Promise.resolve()).then(task)
+        queues.set(sessionID, next.catch(() => {}))
+        return next
+      }
+    }
+
+    const catalog = new Map(skills.map((skill) => [skill.id, skill]))
+    const skillsKey = (sessionID) => `skills/${sessionID}`
+    const skillsInOrder = inOrder()
+    const sessionState = (sessionID) =>
+      skillsInOrder(sessionID, async () => {
+        const { playbook, skip, loaded = [], ran = [] } = (await ctx.storage.get(skillsKey(sessionID))) ?? {}
+        return { mode: await commandedMode(sessionID), playbook, skip, loaded, ran }
+      })
+    const record = (sessionID, event) =>
+      skillsInOrder(sessionID, async () => {
+        const before = await ctx.storage.get(skillsKey(sessionID))
+        const after = withEvent(before, event, catalog)
+        if (after !== before) await ctx.storage.set(skillsKey(sessionID), after)
+      })
+
+    const synced = new Map()
+    const reconcileNow = async (sessionID, agent) => {
+      const mode = agent === MODE_AGENT || (await commandedMode(sessionID))
+      const want = { [MODELS_KEY]: readModels(), [MODE_KEY]: mode ? modeEntry(ROOT) : undefined }
+      let have = synced.get(sessionID)
+      if (!have) {
+        const entries = unwrap(await ctx.session.instructions.entry.list({ sessionID })) ?? []
+        have = Object.fromEntries(entries.filter((entry) => entry.key in want).map((entry) => [entry.key, entry.value]))
+        synced.set(sessionID, have)
+      }
+      for (const { key, value } of entryOps(want, have)) {
+        if (value === undefined) {
+          await ctx.session.instructions.entry.remove({ sessionID, key })
+          delete have[key]
+        } else {
+          await ctx.session.instructions.entry.put({ sessionID, key, value })
+          have[key] = value
+        }
+      }
+    }
+    const reconcileInOrder = inOrder()
+    const reconcile = (sessionID, agent) => reconcileInOrder(sessionID, () => reconcileNow(sessionID, agent))
+    const guarded = (name, hook) => async (event) => {
+      try {
+        await hook(event)
+      } catch (error) {
+        console.error(`pstack: ${name} hook failed`, error)
+      }
+    }
+
+    const shadowingPath = async (sessionID, skill) => {
+      const session = unwrap(await ctx.session.get({ sessionID }))
+      const directory = session?.location?.directory
+      const registered = unwrap(await ctx.skill.list(directory ? { location: { directory } } : undefined)) ?? []
+      const path = registered.find((entry) => entry.id === skill.id)?.path
+      return path && path !== skill.path ? path : undefined
+    }
+
+    await ctx.skill.transform((editor) => {
+      for (const skill of skills) editor.add(skill)
+    })
+
+    await ctx.command.transform((editor) => {
+      for (const skill of skills) {
+        if (skill.kind === "playbook" || skill.id.startsWith("principle-")) continue
+        editor.add({
+          name: skill.id,
+          description: commandDescription(skill.description),
+          execute: async ({ sessionID, prompt, delivery }) => {
+            if (skill.id === MODE_AGENT) await ctx.storage.set(modeKey(sessionID), true)
+            const { text, attach } = commandPrompt(skill, prompt.text ?? "", await shadowingPath(sessionID, skill))
+            const attached = attach ? [...(prompt.skills ?? []), { id: skill.id }] : prompt.skills
+            await ctx.session.prompt({ ...prompt, sessionID, delivery, text, ...(attached ? { skills: attached } : {}) })
+          },
+        })
+      }
+    })
+
+    await ctx.agent.transform((editor) => {
+      for (const agent of agents) {
+        if (editor.get(agent.id)) continue
+        editor.update(agent.id, (draft) => {
+          draft.description = agent.description
+          draft.mode = agent.mode
+          if (agent.color) draft.color = agent.color
+          if (agent.system) draft.system = agent.system
+        })
+      }
+    })
+
+    await ctx.session.hook(
+      "prompt",
+      guarded("prompt", async (event) => {
+        const session = unwrap(await ctx.session.get({ sessionID: event.sessionID }))
+        await reconcile(event.sessionID, session?.agent)
+        if (session?.agent !== MODE_AGENT) return
+        const attachedKey = `attached/${event.sessionID}`
+        if (await ctx.storage.get(attachedKey)) return
+        event.prompt.skills ??= []
+        if (!event.prompt.skills.some((skill) => skill.id === MODE_AGENT)) event.prompt.skills.push({ id: MODE_AGENT })
+        await ctx.storage.set(attachedKey, true)
+      }),
+    )
+
+    await ctx.session.hook(
+      "context",
+      guarded("context", (event) => reconcile(event.sessionID, event.agent)),
+    )
+
+    const real = (path) => {
+      try {
+        return realpathSync(path)
+      } catch {
+        return path
+      }
+    }
+    const within = (path, dir) => {
+      const rel = relative(dir, path)
+      return !rel.startsWith("..") && !isAbsolute(rel)
+    }
+    const readsProject = async ({ sessionID, input }) => {
+      const directory = unwrap(await ctx.session.get({ sessionID }))?.location?.directory
+      const target = real(resolve(directory ?? "", input.path ?? input.filePath ?? "."))
+      return !within(target, ROOT) && (!directory || within(target, real(directory)))
+    }
+
+    await ctx.tool.hook("execute.before", async (event) => {
+      let blocked
+      try {
+        if (isCodeAction(event) || isReadAction(event)) {
+          const session = await sessionState(event.sessionID)
+          blocked = actGate(session, event, catalog) ?? commitGate(session, event)
+          if (blocked && isReadAction(event) && !(await readsProject(event))) blocked = undefined
+        }
+      } catch (error) {
+        console.error("pstack: execute.before hook failed", error)
+      }
+      if (blocked) throw new Error(blocked)
+    })
+
+    await ctx.tool.hook(
+      "execute.after",
+      guarded("execute.after", async (event) => {
+        if (isSkillEvent(event, catalog)) await record(event.sessionID, event)
+      }),
+    )
+  },
+}

package/plugin/lib.js

@@ -0,0 +1,277 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+
+export const MODE_AGENT = "poteto-mode"
+export const MODELS_KEY = "pstack-models"
+export const MODE_KEY = "pstack-mode"
+const MODE_AGENTS = [MODE_AGENT, "poteto-agent"]
+const COMMIT_GATE =
+  "pstack: load the `deslop` skill with the `skill` tool and follow it on the staged diff before you commit. Then rerun `git commit` as its own command, because this whole shell command was rejected and nothing in it ran."
+
+const GIT_COMMIT = /(?:^|[;&|(\n])\s*git(?:\s+-\S+(?:\s+[^-\s;&|]\S*)?)*\s+commit(?=$|[\s;&|)])/
+
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/
+const LINK = /\]\(([^)\s]+)\)/g
+
+function scalar(raw, continuation) {
+  const value = raw.trim()
+  if (value.startsWith('"')) return JSON.parse(value)
+  if (value.startsWith("'")) return value.slice(1, -1).replaceAll("''", "'")
+  if (/^[>|][+-]?$/.test(value)) {
+    const lines = continuation.map((line) => line.trim())
+    return value.startsWith(">") ? lines.filter(Boolean).join(" ") : lines.join("\n").trim()
+  }
+  return value
+}
+
+export function parseFrontmatter(text) {
+  const match = text.match(FRONTMATTER)
+  if (!match) return { data: {}, body: text }
+  const lines = match[1].split(/\r?\n/)
+  const data = {}
+  for (let i = 0; i < lines.length; i++) {
+    const field = lines[i].match(/^([A-Za-z][\w-]*):(.*)$/)
+    if (!field) continue
+    const continuation = []
+    while (i + 1 < lines.length && /^\s+\S/.test(lines[i + 1])) continuation.push(lines[++i])
+    data[field[1]] = scalar(field[2], continuation)
+  }
+  return { data, body: text.slice(match[0].length).replace(/^\s+/, "") }
+}
+
+function absoluteLinks(text, dir) {
+  return text.replace(LINK, (link, href) => {
+    const target = href.replace(/[#?].*/, "")
+    if (!target || /^[a-z][a-z0-9+.-]*:/i.test(target)) return link
+    const path = resolve(dir, target)
+    return existsSync(path) ? `](${path}${href.slice(target.length)})` : link
+  })
+}
+
+const PLAYBOOK_ENTRY = /^- \*\*(.+?)\.\*\* (.+)$/gm
+const ENTRY_ID = / ID: `([a-z0-9-]+)`\.$/
+const STEP = /^\d+\.\s/
+const NAMED_SKILL = /the `([a-z0-9-]+)` skill\b/g
+
+const kebab = (title) =>
+  title
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, "")
+    .trim()
+    .replace(/\s+/g, "-")
+
+export function playbookDescriptions(modeBody) {
+  const section = modeBody.slice(modeBody.indexOf("## Playbooks"))
+  return new Map(
+    [...section.matchAll(PLAYBOOK_ENTRY)].map(([, title, text]) => [text.match(ENTRY_ID)?.[1] ?? kebab(title), text.replace(ENTRY_ID, "")]),
+  )
+}
+
+export function playbookSkills(body) {
+  const lines = body.split("\n")
+  const start = lines.findIndex((line) => STEP.test(line))
+  if (start < 0) return []
+  const end = lines.findIndex((line, index) => index > start && /^\S/.test(line) && !STEP.test(line))
+  const steps = lines.slice(start, end < 0 ? undefined : end).join("\n")
+  return [...new Set([...steps.matchAll(NAMED_SKILL)].map(([, id]) => id))]
+}
+
+const list = (value) => (value ?? "").split(",").map((item) => item.trim()).filter(Boolean)
+export const playbookRequires = (data) => list(data.requires)
+
+function readPlaybooks(modeDir) {
+  const dir = join(modeDir, "playbooks")
+  if (!existsSync(dir)) return []
+  const descriptions = playbookDescriptions(readFileSync(join(modeDir, "SKILL.md"), "utf8"))
+  return readdirSync(dir)
+    .filter((name) => name.endsWith(".md"))
+    .sort()
+    .map((name) => {
+      const id = name.slice(0, -".md".length)
+      const path = join(dir, name)
+      const { data, body } = parseFrontmatter(readFileSync(path, "utf8"))
+      const title = body.match(/^### (.+)$/m)?.[1] ?? id
+      const frame = `This is the \`${MODE_AGENT}\` ${title} playbook. Copy its numbered steps verbatim into the todo list, and when a step names a skill, load that skill with the \`skill\` tool.`
+      return {
+        kind: "playbook",
+        id,
+        name: id,
+        title,
+        description: descriptions.get(id) ?? title,
+        path,
+        content: `${frame}\n\n${absoluteLinks(body, dir)}`,
+        autoinvoke: false,
+        skills: playbookSkills(body),
+        requires: playbookRequires(data),
+        gates: list(data.gates),
+      }
+    })
+}
+
+export function readSkills(skillsDir) {
+  const skills = readdirSync(skillsDir)
+    .filter((id) => existsSync(join(skillsDir, id, "SKILL.md")))
+    .sort()
+    .map((id) => {
+      const path = join(skillsDir, id, "SKILL.md")
+      const { data, body } = parseFrontmatter(readFileSync(path, "utf8"))
+      return {
+        kind: "skill",
+        id,
+        name: data.name || id,
+        description: data.description ?? "",
+        path,
+        content: absoluteLinks(body, dirname(path)),
+        autoinvoke: data["disable-model-invocation"] !== "true",
+      }
+    })
+  const ids = new Set(skills.map((skill) => skill.id))
+  return [...skills, ...readPlaybooks(join(skillsDir, MODE_AGENT)).filter((playbook) => !ids.has(playbook.id))]
+}
+
+const AGENT_MODES = ["primary", "subagent", "all"]
+
+export function readAgents(agentsDir) {
+  return readdirSync(agentsDir)
+    .filter((name) => name.endsWith(".md"))
+    .sort()
+    .map((name) => {
+      const path = join(agentsDir, name)
+      const { data, body } = parseFrontmatter(readFileSync(path, "utf8"))
+      if (!data.description) throw new Error(`pstack: ${path} has no description`)
+      if (!AGENT_MODES.includes(data.mode)) throw new Error(`pstack: ${path} has mode ${JSON.stringify(data.mode)}, expected one of ${AGENT_MODES.join(", ")}`)
+      return {
+        id: name.slice(0, -".md".length),
+        description: data.description,
+        mode: data.mode,
+        ...(data.color ? { color: data.color } : {}),
+        ...(body ? { system: body } : {}),
+      }
+    })
+}
+
+export function commandDescription(description, max = 120) {
+  const sentence = description.match(/^.*?[.!?](?=\s|$)/)?.[0] ?? description
+  if (sentence.length <= max) return sentence
+  return `${sentence.slice(0, sentence.lastIndexOf(" ", max - 3))}...`
+}
+
+export function commandPrompt(skill, text, shadowedBy) {
+  const task = text.trim() || `Run the ${skill.id} skill.`
+  if (!shadowedBy) return { text: task, attach: true }
+  return {
+    text: `Read the pstack \`${skill.id}\` skill at \`${skill.path}\` and follow it. The user skill at \`${shadowedBy}\` has the same ID, so do not load \`${skill.id}\` with the skill tool.\n\n${task}`,
+    attach: false,
+  }
+}
+
+export function modeEntry(root) {
+  return [
+    "poteto mode is on. The user turned it on, so every task in this session follows the `poteto-mode` skill.",
+    `If the skill's instructions are not in this conversation, at the start or after compaction, load it with the \`skill\` tool (ID \`poteto-mode\`, file \`${join(root, "skills", "poteto-mode", "SKILL.md")}\`) before you act.`,
+    'When the user says "new task", match a fresh playbook.',
+  ].join(" ")
+}
+
+export function modelsEntry(file, text) {
+  if (!text) return undefined
+  return `pstack per-role model choices, written by /setup-pstack to \`${file}\`. Each role line overrides that role's default model in pstack skills.\n\n${text}`
+}
+
+export const isCommit = ({ tool, input }) => tool === "shell" && GIT_COMMIT.test(input.command)
+
+export function commitGate(session, event) {
+  if (!isCommit(event)) return undefined
+  if (session.loaded.includes("deslop") || !(session.mode || MODE_AGENTS.includes(event.agent))) return undefined
+  return COMMIT_GATE
+}
+
+const CODE_TOOLS = new Set(["edit", "write", "apply_patch", "patch", "multiedit"])
+const CODE_AGENTS = new Set(["poteto-agent", "general"])
+const SKILL_FILE = /\/skills\/(?:poteto-mode\/playbooks\/([a-z0-9-]+)\.md|([a-z0-9-]+)\/SKILL\.md)$/
+
+export const isCodeAction = (event) => CODE_TOOLS.has(event.tool) || (event.tool === "subagent" && CODE_AGENTS.has(event.input.agent)) || isCommit(event)
+
+export function loadedSkill({ tool, input, status }, skills) {
+  if (status !== "completed") return undefined
+  if (tool === "skill") return input.id
+  if (tool !== "read") return undefined
+  const [, playbook, skill] = input.path?.match(SKILL_FILE) ?? []
+  const id = playbook ?? skill
+  return skills.has(id) ? id : undefined
+}
+
+const spawns =
+  (...agents) =>
+  ({ tool, input }) =>
+    tool === "subagent" && agents.includes(input.agent)
+const runsShell =
+  (pattern) =>
+  ({ tool, input }) =>
+    tool === "shell" && pattern.test(input.command)
+const EXPLORES = { by: spawns("explore"), finish: "spawn its `explore` subagents as the skill says" }
+
+export const RAN = {
+  how: EXPLORES,
+  architect: EXPLORES,
+  arena: EXPLORES,
+  interrogate: { by: spawns("general"), finish: "spawn its `general` adversaries as the skill says" },
+  why: {
+    by: (event) => spawns("general")(event) || runsShell(/\bgit\s+(?:log|blame)\b/)(event),
+    finish: "spawn its `general` subagents, or read the history with `git log` or `git blame`, as the skill says",
+  },
+}
+
+const isEvidence = (event) => Object.values(RAN).some((rule) => rule.by(event))
+
+export const skipsPlaybook = ({ tool, input, status }) =>
+  status === "completed" && tool === "todowrite" && (input.todos ?? []).some((todo) => /^no playbook:/i.test(String(todo.content ?? "").trim()))
+
+export const isSkillEvent = (event, skills) => event.status === "completed" && (Boolean(loadedSkill(event, skills)) || isEvidence(event) || skipsPlaybook(event))
+
+export function withEvent(record, event, skills) {
+  const session = { loaded: [], ran: [], ...record }
+  if (skipsPlaybook(event)) return session.skip ? record : { ...session, skip: true }
+  const id = loadedSkill(event, skills)
+  if (skills.get(id)?.kind === "playbook") return session.playbook === id ? record : { ...session, playbook: id }
+  if (id) return session.loaded.includes(id) ? record : { ...session, loaded: [...session.loaded, id] }
+  if (event.status !== "completed") return record
+  const fresh = session.loaded.filter((loaded) => !session.ran.includes(loaded) && RAN[loaded]?.by(event))
+  return fresh.length === 0 ? record : { ...session, ran: [...session.ran, ...fresh] }
+}
+
+const listed = (items) => (items.length < 2 ? items.join("") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`)
+
+const READ_TOOLS = new Set(["read", "grep", "glob", "list"])
+export const isReadAction = ({ tool }) => READ_TOOLS.has(tool)
+
+const HOLDS = {
+  code: { reason: (skills) => `runs the ${skills} before any code change`, then: (event) => `retry this call${isCommit(event) ? " as its own `git commit` command, because this whole shell command was rejected" : ""}` },
+  reads: { reason: (skills) => `reads the code through the ${skills}`, then: (event, missing) => `use ${missing.length === 1 ? "its" : "their"} findings instead of reading files yourself` },
+}
+
+const PLAYBOOK_FIRST =
+  "pstack: poteto mode runs every task through a playbook. Load the matching playbook with the `skill` tool (Bug fix is `bug-fix`) and follow its steps. For a fully specified one-line edit, add a todo `no playbook: <reason>` instead. Then retry this call"
+
+export function actGate(session, event, skills) {
+  if (!(session.mode || event.agent === MODE_AGENT)) return undefined
+  if (!session.playbook && !session.skip && isCodeAction(event)) return `${PLAYBOOK_FIRST}${isCommit(event) ? " as its own `git commit` command, because this whole shell command was rejected" : ""}.`
+  const playbook = skills.get(session.playbook)
+  const held = isCodeAction(event) ? "code" : isReadAction(event) && playbook?.gates.includes("reads") ? "reads" : undefined
+  if (!held) return undefined
+  const loadsOnly = event.tool === "subagent" && isEvidence(event)
+  const unfinished = (id) => !session.loaded.includes(id) || (!loadsOnly && RAN[id] && !session.ran.includes(id))
+  const missing = playbook?.requires.filter(unfinished) ?? []
+  if (missing.length === 0) return undefined
+  const steps = missing
+    .map((id) => (session.loaded.includes(id) ? `\`${id}\` is loaded but hasn't run: ${RAN[id].finish}` : `load \`${id}\` with the \`skill\` tool and run it`))
+    .join(", then ")
+  const names = `${listed(missing.map((id) => `\`${id}\``))} skill${missing.length === 1 ? "" : "s"}`
+  return `pstack: the ${playbook.title} playbook ${HOLDS[held].reason(names)}. ${steps[0].toUpperCase()}${steps.slice(1)}, then ${HOLDS[held].then(event, missing)}.`
+}
+
+export function entryOps(want, have) {
+  return Object.entries(want)
+    .filter(([key, value]) => value !== have[key])
+    .map(([key, value]) => ({ key, value }))
+}

package/skills/architect/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: architect
+description: "Sketch types, signatures, and module structure before code, then stay in the loop while implementation fills in. Use for /architect, 'architect this', 'design this', or non-trivial work where jumping to code would lock in the wrong shape."
+disable-model-invocation: true
+---
+
+# Architect
+
+Sketch types, function signatures, class shapes, and module boundaries with `not implemented` bodies and pseudocode. Synthesize across multiple model perspectives, then fill in code against the chosen sketch.
+
+## Start
+
+Open a todo list with `todowrite` with one entry per phase before starting.
+
+1. Ground
+2. Sketch
+3. Agree
+4. Implement
+5. Scrap
+
+## Phase A: Ground the problem
+
+Build a real mental model of every system the new code touches. Load the `how` skill with the `skill` tool and run it over the relevant subsystems. Naming a file isn't grounding. Produce the architectural explanation `how` prescribes. If the design redefines ownership or layering, also load and run the `why` skill on the existing shape so the rationale becomes a constraint, not a guess.
+
+Skip Phase A only when the work is genuinely greenfield with no surrounding system to integrate.
+
+## Phase B: Sketch
+
+Load the `arena` skill and run it with the design-sketch task and the Phase A grounding artifacts. Pass `references/runner-prompt.md` as each runner's prompt.
+
+Take the runners from the `architect runners` line in the `pstack-models` instruction entry, in place of the `arena runners` line. If the entry or that line is missing, use `<provider>/claude-opus-5-5#xhigh` and `<provider>/grok-4.7#xhigh`, from a provider that lists each. Alias and rejected entries follow the runner rules in the `arena` skill's Phase A.
+
+Design it twice. Require at least two structurally distinct candidates before synthesis, even when the first looks sufficient. This is the `principle-exhaust-the-design-space` skill made concrete. Whole-shape alternatives, not point fixes inside one shape.
+
+Screen every candidate against [`references/design-red-flags.md`](references/design-red-flags.md) before synthesis. Assume the next contributor is an agent that sees only the files it opened, copies the nearest example, and takes the shortest path that compiles. Prefer the design where a change that looks right from one file is right for the whole repo.
+
+Compare viable candidates on interface depth. Prefer the design that hides more complexity behind a smaller, simpler public surface. A rich interface can keep call chains short by concentrating capability instead of scattering it across layers.
+
+Arena returns one synthesized design package. Its synthesis decision fills the rationale's "Synthesis decision" section.
+
+## Phase C: Agree (opt-in)
+
+Default: proceed directly to implementation with the synthesized design. No human checkpoint.
+
+Opt in to a checkpoint when the invoker explicitly asks: "/architect with checkpoint," "stop and show me before implementing," or similar. Then surface the synthesized design and pause for sign-off.
+
+The synthesis can ship as its own commit either way, as the "scaffold first" mode of the `principle-foundational-thinking` skill. Planned and scoped breakage during fill-in is fine, per the `principle-outcome-oriented-execution` skill. For adversarial pressure on the design before implementing, load and run the `interrogate` skill on the synthesized sketch.
+
+If the human pushes back on the shape (in a checkpoint or after the fact), treat that as Phase A evidence. Re-ground and re-run Phase B before writing more code.
+
+## Phase D: Implement against the sketch
+
+Replace `not implemented` bodies with code, pseudocode with logic. The synthesized sketch is the contract. Deviations from it are signal to surface, not friction to absorb silently. If a function needs a parameter the sketch didn't anticipate, ask whether the sketch was wrong, the requirement was missed, or the implementation is overreaching.
+
+## Phase E: Scrap when the architecture is wrong
+
+If implementation keeps producing friction the sketch can't absorb, throw the sketch out. Don't bolt fixes onto a wrong design, per the `principle-redesign-from-first-principles` and `principle-fix-root-causes` skills.
+
+The signal is a *pattern*, not single instances. Tells:
+
+- The same shape of workaround appearing repeatedly across unrelated code.
+- Multiple unrelated edge cases that all need special-case branches.
+- Types that need escape hatches (`any`, casts, optional fields always set in practice) to compile.
+- The "we need a lock" reflex when the sketch said the state wasn't shared.
+- Callers having to know the abstraction's internal rules to use it.
+- Two or more independent Phase D deviations of the same shape across the implementation.
+
+Use judgment. A few edge cases don't condemn an architecture. Some problems are legitimately complex. Complexity in the data is not complexity in the design.
+
+When you scrap:
+
+1. Load and re-run the `how` skill over what's been built.
+2. Redesign as if the new constraints had been day-one assumptions, per the `principle-redesign-from-first-principles` skill.
+3. Subtract before adding, per the `principle-subtract-before-you-add` skill. The new sketch should be smaller than the old one before it grows.
+4. Return to Phase B and re-run arena.
+
+## Outputs
+
+The caller's usage is written first and the type sketch derived from it. One file with new types and signatures for small changes. Module map plus type definitions for larger work. The rationale ships alongside, shaped per `references/rationale-template.md`, including the usage sketch and the synthesis decision.