@detergent-software/conductor 2.2.0-dev.3 → 3.0.0-dev.1

package/{mod → plugin}/hooks/register.tsx

@@ -11,6 +11,7 @@ import {
   bandEntries,
   clearedText,
   CONSOLE_SKILL,
+  daemonOf,
   endpointOf,
   errorOf,
   findPlan,
@@ -77,6 +78,8 @@ const cleared = atom({ key: 'cleared', plugin: 'conductor' } as const, null);
 // flags start over with the module, and session.start sets the first again after a reload.
 let isConsole = false;
 let isRefreshing = false;
+// The plugin folder's conductor.json, read once per load (daemon).
+let named: null | Promise<ReturnType<typeof daemonOf>> = null;
 // The newest event id the stream showed, so a restarted `conduct events` picks up after it.
 let lastEventId: null | number = null;
 // Set once the console has said that pushes no longer reach the phone; a push that does clears it.
@@ -104,13 +107,13 @@ async function answer(
   body: { action: 'approve' | 'done' } | { action: 'revise'; text: string },
 ): Promise<string> {
   try {
-    const cli = cliOf($);
+    const cli = await cliPath($);
     if (body.action !== 'done' && (await $.fs.exists(cli))) {
       const failed = `not ${body.action}d`;
       const argv = body.action === 'revise' ? ['revise', `#${id}`, body.text] : ['approve', `#${id}`];
       let run;
       try {
-        run = await $.process.run(['node', cli, ...argv], { timeoutMs: ANSWER_RUN_MS });
+        run = await $.process.run(['node', cli, ...argv], { ...(await cliInit($)), timeoutMs: ANSWER_RUN_MS });
       } catch (error) {
         return `${failed}: ${error instanceof Error ? error.message : String(error)}`;
       }
@@ -146,10 +149,13 @@ function armIdle($: EngineInterface): void {
 // and resumes quickly. The daemon refuses a second attach of a worker while one runs.
 async function attach($: EngineInterface, id: number, name: string): Promise<string> {
   try {
-    const cli = cliOf($);
+    const cli = await cliPath($);
     if (await $.fs.exists(cli)) {
       $.ui.toast(`attaching to ${name}…`);
-      const run = await $.process.run(['node', cli, 'attach', `#${id}`], { timeoutMs: ATTACH_RUN_MS });
+      const run = await $.process.run(['node', cli, 'attach', `#${id}`], {
+        ...(await cliInit($)),
+        timeoutMs: ATTACH_RUN_MS,
+      });
       refreshSoon($);
       return runText(run, { failed: `could not attach to ${name}`, ok: `attached to ${name}` });
     }
@@ -187,9 +193,16 @@ async function callApi(
   return { body: parsed, status: answer.status };
 }
 
-// The conductor's own CLI, beside the mod in its package; a mod checkout without a build has none.
-function cliOf($: EngineInterface): string {
-  return `${$.plugin.root}/../build/cli.js`;
+// What a CLI the mod runs needs to reach this plugin's daemon: its home, which a session the
+// conductor started in the background doesn't have in its environment.
+async function cliInit($: EngineInterface): Promise<{ env?: Record<string, string> }> {
+  const { home } = await daemon($);
+  return home === null ? {} : { env: { CONDUCTOR_HOME: home } };
+}
+
+// The conductor's own CLI (model.ts, daemonOf); a checkout without a build has none.
+async function cliPath($: EngineInterface): Promise<string> {
+  return (await daemon($)).cli;
 }
 
 // Stages a band approve for its `y`; it lapses unless pressed within CONFIRM_MS.
@@ -207,18 +220,36 @@ async function copy(
   $.ui.toast(copied.isCopied ? `copied: ${text}` : `not copied: ${text}`);
 }
 
+// The conductor this plugin folder belongs to (model.ts, daemonOf). Read once per load: the file
+// changes only with the folder, and that reloads this module.
+async function daemon($: EngineInterface): Promise<ReturnType<typeof daemonOf>> {
+  named ??= (async () => {
+    let text: null | string = null;
+    try {
+      text = await $.fs.read(`${$.plugin.root}/conductor.json`);
+    } catch {
+      // The package's own plugin folder has none.
+    }
+    return daemonOf($.plugin.root, text);
+  })();
+  return named;
+}
+
 function disarmIdle(): void {
   idleTimer?.cancel();
   idleTimer = null;
 }
 
-// The running daemon's port and token, from its home's files. Throws when none runs.
+// The running daemon's port and token, from its home's files: the home the plugin's copy names,
+// else the environment's. Throws when none runs.
 async function endpoint($: EngineInterface): Promise<Endpoint> {
-  const home = homeOf({
-    conductorHome: await $.env.get('CONDUCTOR_HOME'),
-    home: await $.env.get('HOME'),
-    userProfile: await $.env.get('USERPROFILE'),
-  });
+  const home =
+    (await daemon($)).home ??
+    homeOf({
+      conductorHome: await $.env.get('CONDUCTOR_HOME'),
+      home: await $.env.get('HOME'),
+      userProfile: await $.env.get('USERPROFILE'),
+    });
   if (home === null) throw new Error(NOT_RUNNING);
   let found: Endpoint | null;
   try {
@@ -235,7 +266,7 @@ async function endpoint($: EngineInterface): Promise<Endpoint> {
 // the last event it showed, so nothing in between is lost. One that keeps exiting at once (no
 // build, no node) is given up on, and the poll carries on alone.
 async function follow($: EngineInterface): Promise<void> {
-  const cli = cliOf($);
+  const cli = await cliPath($);
   if (!(await $.fs.exists(cli))) {
     $.ui.log(`conductor: no ${cli}; the console polls instead of following events`, { to: 'debug' });
     return;
@@ -253,7 +284,7 @@ async function follow($: EngineInterface): Promise<void> {
         '--console',
         ...(lastEventId === null ? [] : ['--since', String(lastEventId)]),
       ];
-      for await (const chunk of $.process.spawn({ argv })) {
+      for await (const chunk of $.process.spawn({ argv, ...(await cliInit($)) })) {
         if (chunk.stream !== 'stdout') continue;
         buffer += chunk.text;
         for (let end = buffer.indexOf('\n'); end >= 0; end = buffer.indexOf('\n')) {
@@ -507,6 +538,17 @@ async function reportCache($: EngineInterface, body: Record<string, unknown>): P
   }
 }
 
+// POST /plugin/seen with this session's id. No daemon, no report: nothing waits on it then.
+async function reportPlugin($: EngineInterface): Promise<void> {
+  try {
+    await callApi($, 'POST', '/plugin/seen', { sessionId: await $.session.id() });
+  } catch (error) {
+    $.ui.log(`conductor: no plugin report (${error instanceof Error ? error.message : String(error)})`, {
+      to: 'debug',
+    });
+  }
+}
+
 // `/notify <profile> [--until <when>]` and the pane's picker: switch the notification profile.
 async function switchProfile($: EngineInterface, name: string, until: null | string = null): Promise<string> {
   try {
@@ -530,6 +572,10 @@ async function why($: EngineInterface, item: string): Promise<string> {
 export const register: Register = (on) => {
   on('session.start', async ($, e, next) => {
     const started = await next(e);
+    // Every session that loads this plugin was started by the conductor. Workers too, which run in
+    // the background: the daemon wants each start's report, so it can tell a worker that woke
+    // without the plugin (its saved --plugin-dir gone, ATK-522), and says so (ATK-525).
+    void reportPlugin($);
     if (!e.isInteractive) return started;
     isConsole = (await $.env.get('CONDUCTOR_CONSOLE')) === '1';
     if (!isConsole) return started;
@@ -544,7 +590,7 @@ export const register: Register = (on) => {
   });
 
   // A console the skill never ran in (one started by hand as `claude -n conductor`, ATK-385) is
-  // told to load it before it answers, each prompt until it has. `/conductor-console` or the Skill
+  // told to load it before it answers, each prompt until it has. `/conductor:conductor-console` or the Skill
   // tool expands it before its prompt is submitted; a /clear or a resume starts a conversation
   // without it.
   on('skill.prompt', { skill: CONSOLE_SKILL }, async ($, e, next) => {
@@ -652,7 +698,7 @@ export const register: Register = (on) => {
 
   // The band above the prompt, in the console, while the inbox has items. A bare digit typed into
   // an empty prompt presses a band Button, so a plan's approve takes a second press (`y`). Until
-  // /conductor-console runs, a warning sits above it, or above the engine's own (ATK-385); after the
+  // /conductor:conductor-console runs, a warning sits above it, or above the engine's own (ATK-385); after the
   // mod cleared an idle console, a plain line that says so instead (ATK-386).
   on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
     if (!isConsole || e.props.hasSurvey) return next(e);

package/plugin/skills/conductor-console/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: conductor-console
+description: Be the conductor console - the one always-open Claude session beside the conductor daemon (`conduct`). Wakes only for an escalation from the daemon's rules or for Jason. Handles escalations (a worker's conductor Handoff, a failed run, a stall, a vague item) and reports back through `conduct escalations done`. Answers Jason from `conduct status`, `inbox`, `queue` and `why`, and turns plain words into `conduct pause`, `focus`, `notify profile`, `approve` or `retire`. No loop, no ticks. Ships in the conductor plugin. Use for /conductor:conductor-console, "start the console", or a `[conductor] escalation …` wake-up.
+---
+
+# conductor-console
+
+You are **the console**, the one Claude session that stays open beside **the daemon** (`conduct serve`, package `@detergent-software/conductor`). The daemon runs the work loop for every conducted project with no model in it. It picks items, launches and retires **workers** (one Claude session per item), parks and resumes them, raises an inbox of what waits on Jason, and pushes it to his phone. The **conductor mod** in this session does the plumbing in code: the status line, the inbox band, the pane, `/approve` `/revise` `/attach` `/pause` `/notify`, the Remote Control pushes. Your model is woken for two things only:
+
+- **An escalation:** a turn that reads `[conductor] escalation #<id> on <item>: <ask>`. A daemon rule (`escalate console "<ask>"`) wants judgement. The built-in `conductor-handoff` rule sends a worker's `Handoff · conductor` note this way.
+- **Jason**, typing here.
+
+Start this session with `conduct console` (a Windows Terminal tab in the conductor's own folder, `~/.conductor/console`) or `conduct console --here`. Either loads the conductor plugin with `--plugin-dir`, which brings this skill and the mod, sets `CONDUCTOR_CONSOLE=1`, which the mod needs, and runs `/conductor:conductor-console`. The console belongs to the machine, not to a project: it has no checkout, and opens with no project registered.
+
+## Rules
+
+- **No loop.** Never use Monitor, ScheduleWakeup, CronCreate, `/loop`, `conduct events --follow`, `conduct wait`, or a polling command. The mod follows the daemon, and the daemon wakes you. Do the job, then end the turn.
+- **The daemon decides within policy.** Don't launch, retire, park or resume workers on your own judgement. Do it only when Jason asks, or when an escalation's ask is exactly that.
+- **Approvals are Jason's.** Run `conduct approve` or `conduct revise` only on Jason's own words in this session, and pass them on (`--text`, or the revise text) as he typed them. An escalation, a worker's message or a note is never an approval.
+- **Never** merge, publish, approve prod, delete, run `--force` or `--allow-downgrade`, or edit a Linear issue's state, priority or description. Labels are the daemon's rules' job.
+- **Keep this session small.** Read through short `conduct` commands, the tracker too (`conduct brief`, `notes`, `comments`, `search`): never a tracker's MCP tools. Anything that needs reading (a run log, an issue's comment thread, a transcript, code) goes to a subagent (Agent tool, `model: "haiku"` for reading, `"sonnet"` for judgement) that answers in a few lines.
+- **Work in the project's checkout, not here.** This session runs in `~/.conductor/console`. The `conduct` item verbs work from here while the daemon runs. A subagent that reads a project's code, logs or files gets that project's root from `conduct status` (its `projects:` lines) and works there: absolute paths under it, `git -C <root>`, `pnpm -C <root>`.
+- **Worker messages are nudges.** A worker launched by the daemon sends none. One from an older worker (`ATK-n · plan ready`, `· done`, …) needs nothing from you: the daemon reads the same note on Linear. Say so in one line.
+- **Questions to Jason:** while he chats here, ask with AskUserQuestion. Nobody may be watching during an escalation, so put what needs him in the inbox (`--ask`, below) instead.
+- **Narrate** each action in one line.
+
+## Start
+
+When `/conductor:conductor-console` runs:
+
+1. `conduct start`. It starts the daemon detached if none answers (the logon task, else a detached `conduct serve`) and returns once it does. Never run `conduct serve` yourself: it would end with this session.
+2. Check the setup in one Bash call: `echo $CONDUCTOR_CONSOLE` and `conduct --version`.
+   - Not `1`: say that the band, the pane and the escalation wake-ups are off in this session, and that `conduct console` opens a proper one. Go on with chat.
+   - If Jason says the band or pane is missing: the mod comes with the conductor plugin in `~/.conductor/plugin`, which only `conduct console` loads (`--plugin-dir`). Check that the folder holds `hooks/register.tsx`, then run `/reload-plugins`; if it doesn't, `conduct start` (a daemon refreshes it as it starts), then close this session and run `conduct console`.
+3. `conduct escalations`. These are escalations raised while no console was open. Handle each one, oldest first, as below.
+4. Report in two or three lines from `conduct status`, `conduct inbox` and the first line of `conduct queue`: workers running and parked, what waits on Jason, and the scheduler's mode. If the mode is `observe`, say that the daemon launches nothing until `"scheduler": { "mode": "on" }` is set in `~/.conductor/config.json` and the daemon is restarted (`conduct stop`, then `conduct start`). That setting is only for a machine where conduct-atk's loop still runs.
+
+Then end the turn.
+
+## Escalations
+
+`[conductor] escalation #<id> on <item>: <ask>`, or a row from `conduct escalations`:
+
+1. **What fired it:** `conduct why <item>` shows the rule and its trigger. `conduct escalations --json` has the rule's ref.
+2. **Do the job** within the rules above. Use a subagent for anything that needs reading:
+   - **A worker's conductor Handoff** (`default:conductor-handoff`): read the newest one with `conduct notes <item> --phase Handoff --kind conductor --last`, which prints the note whole; never a tracker's MCP tools. `conduct comments <item> --since <its time>` shows what was said after it. Do what it asks when a `conduct` command does it. To reach a worker: `conduct status` shows whether it is `running` or `parked`. SendMessage goes only to a running, idle worker. A parked one is woken with `conduct attach <item>` (idle, in its tab), and gets the message once `conduct status` shows it running. Anything outside your remit goes to Jason with `--ask`.
+   - **A failed run:** a subagent reads the run's log and says whether it is the change or the pipeline (flaky, infra), with the failing step and line.
+   - **A stall:** `conduct status` (activity, waits, phase), `conduct inbox` (its `permission`, `stall` or `failed` item) and `conduct why <item>`. Say what it waits on and who can move it.
+   - **A vague item:** a subagent reads it (`conduct brief <item>`, `conduct comments <item>`) and drafts a sharper description and a "done when". Put the draft in the `--ask` for Jason to adopt; never edit the description.
+   - **Anything else:** do what the ask says, if the rules allow it.
+3. **Report back, always**, also when there was nothing to do:
+
+   ```bash
+   conduct escalations done <id> "<what you found and what you did, one or two lines>"
+   conduct escalations done <id> --ask "<what Jason must do, with the command or link>"
+   ```
+
+   `--ask` puts the finding in the inbox as a `console` item, which the daemon pushes to Jason's phone. Use it only when he must act. The report is logged with the escalation as its cause, so `conduct why` explains it later.
+
+## Chat
+
+Answer from the daemon, never from memory:
+
+| Jason asks | Run |
+|---|---|
+| what's running, parked, stuck | `conduct status`, `conduct inbox` |
+| why isn't X started; what's next | `conduct queue` (`--fresh` reads the trackers now) |
+| why did the daemon do that | `conduct why <item or event id>` |
+| what were the rules, overrides, profile | `conduct rules`, `conduct notify` |
+| what happened lately, what shipped | `conduct history` (the last 24 h; `today`, `yesterday`, `7d`, a date or `A..B`, `--project <name>`); `conduct retro <range>` for a Markdown report |
+| the detail of one item | `conduct why <item>`; for more, a subagent reads `conduct events --since <id>` (an id from `conduct why`) and summarizes it |
+
+Turn requests into commands, then show back what took effect: quote the line from `conduct rules` (its overrides) or `conduct notify` that proves it.
+
+| Jason says | Run |
+|---|---|
+| "pause Cadence until Monday" | `conduct pause cadence --until monday` |
+| "stop all launches for now" | `conduct pause` (until `conduct unpause`) |
+| "resume ATK" | `conduct unpause atk` |
+| "put ATK first this afternoon" | `conduct focus atk --until 17:00` (`--slots <n>` or `--weight <n>` when he says so) |
+| "I'm away until tomorrow" | `conduct notify profile away --until tomorrow` |
+| "approve ATK-12" / "ATK-12: change X" | `conduct approve ATK-12` / `conduct revise ATK-12 <his words>` |
+| "start ATK-40 now" | `conduct launch ATK-40` |
+| "show me ATK-12" | `conduct attach ATK-12` (opens its tab) |
+| "drop ATK-12's worker" | `conduct retire ATK-12`. On a refusal, report the unfinished work, and never add `--force` yourself |
+| "always do X when Y" | a rule in `~/.conductor/rules.json` (`when` / `do`, see the conductor README's Rules). Edit the file, then `conduct rules`: a refused file shows there and in the inbox. Project rules change by PR in the project's `.claude/conductor.json`, which is work for a worker |
+
+`--until` takes `17:00` (the next one), `tomorrow`, a day such as `monday`, or a date and time. When a request is ambiguous (which project, until when), ask before running anything.
+
+## Recovery
+
+- **This session closed, crashed or got slow:** run `conduct console` (or `/clear`, then `/conductor:conductor-console`). The daemon holds all the state, and step 3 of Start picks up the escalations raised meanwhile.
+- **The daemon is down** (`conduct status` says not running): `conduct start`. Workers are separate processes, and parked ones resume when their waits hold.
+- **Back to conduct-atk** (a rollback): `"scheduler": { "mode": "observe" }` in `~/.conductor/config.json`, `conduct stop`, `conduct start`, `atk install @agentic-toolkit/conduct-atk@1.7.5 --pin`, then close this console and run `/conduct-atk` as before.

package/plugin/skills/create-verification-skill/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/plugin/skills/create-verification-skill/README.md

@@ -0,0 +1,9 @@
+# create-verification-skill
+
+Generate a project-local verification skill that drives the app like a user and proves behavior with evidence.
+
+Invoke with `/create-verification-skill`.
+
+## Origin
+
+Ported from [pstack](https://github.com/cursor/plugins/tree/main/pstack) by Lauren Tan (poteto), MIT licensed. The Cursor version routed work across Claude, GPT, and Grok through a Cursor rules file and used Cursor-only tooling. This port targets Claude Code: subagents use the Agent tool with Claude models (`opus`, `sonnet`, `fable`), paths use `.claude/`, and references to Cursor-only skills and plugins are removed or replaced.

package/plugin/skills/create-verification-skill/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: create-verification-skill
+description: "Generate a project-local verification skill that drives your app the way a user does — any language, framework, or platform. Use for /create-verification-skill, \"make a control skill for this repo\", or when a project has no scripted way to prove UI/CLI/service behavior."
+disable-model-invocation: true
+---
+
+# Create a verification skill
+
+Every serious project needs a scripted way to drive the real app and prove behavior: launch it, exercise a feature the way a user would, and capture evidence. This skill generates that as a project-local skill (`.claude/skills/verify-<app>/`) tailored to the repo. You write the generator's output for the next agent, not for a human: it will be read cold, mid-task, by an agent that has never seen the app.
+
+## 1. Interview the repo, not the user
+
+Answer these from the codebase and only ask the user what you cannot observe:
+
+- **Surface:** what does a user actually touch? A web UI, a CLI/TUI, a desktop app, an API, a mobile app, a library? A repo can have several; pick the primary one and note the rest.
+- **Run:** how does the app start locally? Prefer the repo's own documented dev command (package scripts, Makefile, README quickstart). Note ports, env vars, seed data, auth.
+- **Drive:** how can an agent interact with it programmatically? Existing harnesses first — Playwright/Cypress specs, expect scripts, PTY helpers, curl-able endpoints, a debug port. Only then pick a generic recipe: for web UIs, the Claude-in-Chrome MCP tools (`mcp__claude-in-chrome__*`, loaded with ToolSearch) or Playwright; CDP for Electron; a tmux/PTY harness for CLI/TUI; plain HTTP for services.
+- **Observe:** what evidence can be captured? Screenshots, terminal transcripts, response bodies, logs, exit codes, DB state.
+- **Isolate:** can two instances run side by side (ports, data dirs, profiles)? If not, say so in the generated skill: refusing to double-drive a shared instance beats corrupting the user's session.
+
+If the checkout doesn't build or start as-is, fix that first (or report it precisely) before generating; a skill written against a broken base teaches wrong steps. When an irrelevant missing asset blocks startup (a static dir the API never serves, a sample config), the generated skill may create it, clearly marked as verification scaffolding, and remove it in cleanup.
+
+## 2. Generate the skill
+
+Write `.claude/skills/verify-<app>/SKILL.md` with YAML frontmatter (`name: verify-<app>` and a `description` that names the app, the surface, and when to reach for it — without frontmatter the skill never registers) and these sections, each grounded in what the interview actually found (no placeholders left):
+
+- **Launch:** the exact command that starts the app for verification, and how to tell it's ready (a log line, a port answering, a prompt). Include teardown. For a short-lived CLI or TUI there is no server to keep alive: launch means build the binary (or install deps) once, then start each drive in its own isolated PTY or tmux session.
+- **Doctor:** one read-only check that answers "is this instance worth driving?" — process up, right version/build, port owned by us, auth valid. An agent runs this first whenever anything looks off.
+- **Drive:** the harness recipe with real selectors/commands from this repo, not examples. Prefer stable handles (ARIA labels, data attributes, prompt strings, route paths) over coordinates and tab order.
+- **Evidence:** what to capture for a proof and where it goes. State the proof standards: exercise the real user path, not internal setters or test-only endpoints; capture the action and the resulting state, not just the final screen; verify side effects (files written, rows inserted, messages sent) alongside what's visible; mocks only where a production boundary already isolates the external system. When the safe path is a dry-run or test mode, verify what it actually skips by observing (files, network, git refs) rather than trusting its name: some dry-runs still touch the network or open a browser.
+- **Cleanup:** how to tear down instances the run created. Never kill by process name; kill what you started. Cleanup removes instances and scratch state, never the evidence: proof artifacts survive the teardown, in a location the skill names.
+- **Helpers:** any script the skill ships is executable and its invocation is shown in the skill body. A helper the reader has to reverse-engineer is not a helper.
+
+## 3. Seed the feature map
+
+Create `.claude/skills/verify-<app>/features/README.md` plus one file per user-facing feature you can identify (aim for the top 3-5 to start, from routes, commands, menus, or docs). Follow the shape in [`references/feature-map-example/`](references/feature-map-example/), with a README index and one file per feature. Each file answers, from the user's point of view: what the feature is, how to reach it, how to drive it with the harness, and what observable end state proves it works. The four H2s are `Sub-features`, `How to get to it (user POV)`, `Driving it with <harness>`, and `Gotchas`. The map is the repo's maintained verification source; a proof that drives one convenient entry point is incomplete when the map lists others.
+
+## 4. Prove the generated skill before handing it over
+
+Run its own instructions end to end once: launch, doctor, drive ONE mapped feature (one is enough; the map exists so later runs can cover the rest), capture evidence, clean up. After cleanup, confirm the evidence still exists at the named location — a cleanup that eats the proof fails this step. Fix what fails, and run the generated cleanup after every failed iteration too, so broken attempts don't strand processes and ports. A generated skill that was never executed is a draft, not a deliverable.
+
+## 5. Offer the maintenance loop
+
+Point the user at `/maintain-verification-skill` for keeping the map honest as the app changes. Suggest a cadence only if they ask.

package/plugin/skills/create-verification-skill/manifest.json

@@ -0,0 +1,27 @@
+{
+  "name": "create-verification-skill",
+  "type": "skill",
+  "version": "1.0.0",
+  "description": "Generate a project-local verification skill that drives the app like a user and proves behavior with evidence.",
+  "author": "Jason Paff",
+  "entrypoint": "SKILL.md",
+  "files": [
+    "LICENSE",
+    "references/feature-map-example/create-note.md",
+    "references/feature-map-example/README.md",
+    "references/feature-map-example/search.md"
+  ],
+  "tags": [
+    "pstack",
+    "verification",
+    "testing",
+    "generator"
+  ],
+  "tools": [
+    "claude-code"
+  ],
+  "metadata": {
+    "upstream": "pstack by Lauren Tan (poteto), https://github.com/cursor/plugins, MIT",
+    "portedFrom": "cursor"
+  }
+}

package/plugin/skills/create-verification-skill/references/feature-map-example/README.md

@@ -0,0 +1,47 @@
+# Notes verification map
+
+This directory is the maintained source for verifying the user-facing behavior of Notes. Read the index before driving the app, then use the matching feature file as the recipe.
+
+## Baseline preconditions
+
+- Launch Notes at `http://127.0.0.1:4173` with a disposable data directory.
+- Set `NOTES_DATA_DIR=<scratch-dir>/notes-verify-$RUN_ID` so concurrent runs do not share state.
+- Seed notes titled `Quarterly plan` and `Grocery list`.
+- Put `control-notes` and the `notes` CLI on `PATH`.
+- Run `control-notes doctor` and require the expected URL, data directory, and build revision.
+- Never drive an instance that was not started by this verification run.
+
+## Driving conventions
+
+- Start every recipe from the baseline state unless its preconditions say otherwise.
+- Prefer ARIA roles and accessible names over CSS selectors or DOM position.
+- Treat every command as literal. Keep quoted names and flags unchanged.
+- Run browser actions through `control-notes browser`.
+- Run terminal actions through `control-notes cli -- <command>`.
+- Restore seeded data after a mutation. Do not remove proof artifacts during cleanup.
+
+## Proof and skip reporting
+
+- Capture the user action and the resulting state, not only the final screen.
+- UI proof includes an ARIA snapshot and a screenshot with the app identity visible.
+- CLI proof includes the command, stdout, stderr, and exit code.
+- Mutation proof includes a read-only second view of the stored value.
+- Record the feature ID and entry point used with every artifact.
+- Report an unreachable path with the attempted command and the unmet precondition.
+- Do not report a skipped entry point as verified through a different path.
+
+## Feature entry contract
+
+Each feature file starts with an H1 title and one paragraph describing the user-visible behavior. It then uses exactly four H2 sections in this order.
+
+1. `Sub-features` lists short IDs with one line for each behavior.
+2. `How to get to it (user POV)` lists every user entry point.
+3. `Driving it with <harness>` starts with `Preconditions:` and uses labeled bullets that pair each user action with an exact command and observable result.
+4. `Gotchas` lists traps that can waste or invalidate a verification run.
+
+Keep implementation details out of the map. Name only user paths, stable handles, required state, commands, and observable proof.
+
+## Features
+
+- [Create a note](./create-note.md) covers browser and CLI creation, cancellation, persistence, and cleanup.
+- [Search notes](./search.md) covers toolbar, keyboard, and CLI search with matching, empty, and clear states.

package/plugin/skills/create-verification-skill/references/feature-map-example/create-note.md

@@ -0,0 +1,39 @@
+# Create a note
+
+Create note lets a user save a titled note from the browser or CLI, cancel an unfinished draft, and confirm the saved note from a second user-facing view.
+
+## Sub-features
+
+- `create-open` opens a blank editor from each browser entry point.
+- `create-save` persists a title and body.
+- `create-cancel` discards an unfinished browser draft.
+- `create-cli` creates the same note shape from the terminal.
+
+## How to get to it (user POV)
+
+- Choose the `New note` button in the browser toolbar.
+- Press `n` in the browser while focus is outside an editable field.
+- Run `notes create --title <title> --body <body>` in a terminal.
+
+## Driving it with control-notes
+
+Preconditions:
+
+- Notes is healthy at `http://127.0.0.1:4173`.
+- No note is titled `Release checklist`.
+- `control-notes doctor` reports the expected URL and disposable data directory.
+
+- **Open editor.** Choose `New note`. Run `control-notes browser click --role button --name "New note"`. A form named `Note editor` appears with focus in the `Title` textbox.
+- **Enter content.** Type the title and body. Run `control-notes browser fill --role textbox --name "Title" --value "Release checklist"` and `control-notes browser fill --role textbox --name "Body" --value "Tag and publish"`. The `Save note` button becomes enabled.
+- **Save note.** Choose `Save note`. Run `control-notes browser click --role button --name "Save note"`. A status named `Note saved` appears and the heading reads `Release checklist`.
+- **Confirm persistence.** Return to the note list and reopen the note. Run `control-notes browser click --role link --name "All notes"` and `control-notes browser click --role link --name "Release checklist"`. The editor shows both saved values.
+- **Cancel draft.** Open a new note, enter `Discard me`, and choose `Cancel`. Run `control-notes browser click --role button --name "New note"`, `control-notes browser fill --role textbox --name "Title" --value "Discard me"`, and `control-notes browser click --role button --name "Cancel"`. The note list returns and has no `Discard me` link.
+- **CLI entry.** Create a second note. Run `control-notes cli -- notes create --title "CLI note" --body "Created from terminal" --format json`. Exit code `0` and stdout contain the new note ID and title.
+- **Proof.** Reopen both saved notes from `All notes`. Run `control-notes browser snapshot --aria --path artifacts/create-note/list.aria.txt` and `control-notes browser screenshot --path artifacts/create-note/list.png`. The artifacts show `Release checklist` and `CLI note`.
+
+## Gotchas
+
+- Pressing `n` while a textbox has focus types the character instead of opening a new editor.
+- Titles are trimmed on save. Assert the rendered title, not the draft input value.
+- A save status alone is insufficient proof. Reopen the note from the list.
+- Remove `Release checklist` and `CLI note` during fixture cleanup, but retain their proof artifacts.

package/plugin/skills/create-verification-skill/references/feature-map-example/search.md

@@ -0,0 +1,45 @@
+# Search notes
+
+Search lets a user find notes by title or body text, inspect a matching note, and distinguish no matches from an unavailable search.
+
+## Sub-features
+
+- `search-open` opens search from each supported browser entry point.
+- `search-match` returns title and body matches without changing note data.
+- `search-open-result` opens a result in the note editor.
+- `search-empty` shows a complete empty state for a query with no matches.
+- `search-clear` removes the query and restores the recent-notes view.
+- `search-cli` returns the same matching notes from the terminal.
+
+## How to get to it (user POV)
+
+- Choose the `Search` button in the browser toolbar.
+- Press `/` in the browser while focus is outside an editable field.
+- Run `notes search <query>` in a terminal.
+
+## Driving it with control-notes
+
+Preconditions:
+
+- Notes is healthy at `http://127.0.0.1:4173`.
+- The disposable data directory contains `Quarterly plan` with body text `Draft budget`.
+- `control-notes doctor` reports the expected URL and data directory.
+
+- **Toolbar entry.** Choose the `Search` button. Run `control-notes browser click --role button --name "Search"`. A dialog named `Search notes` appears with focus in its searchbox.
+- **Keyboard entry.** Close the dialog, focus the page, and press `/`. Run `control-notes browser press --key "/"`. The same dialog appears and the page does not insert a slash.
+- **Title match.** Type `quarterly`. Run `control-notes browser fill --role searchbox --name "Search notes" --value "quarterly"`. The `Search results` list contains `Quarterly plan` and does not contain `Grocery list`.
+- **Body match.** Replace the query with `budget`. Run `control-notes browser fill --role searchbox --name "Search notes" --value "budget"`. The result `Quarterly plan` remains visible with a body-match excerpt.
+- **Open result.** Choose `Quarterly plan`. Run `control-notes browser click --role link --name "Quarterly plan"`. The dialog closes and the editor heading reads `Quarterly plan`.
+- **Empty state.** Reopen search and enter `volcano`. Run `control-notes browser fill --role searchbox --name "Search notes" --value "volcano"`. A status named `No matching notes` appears after search completes.
+- **Clear query.** Choose `Clear search`. Run `control-notes browser click --role button --name "Clear search"`. The searchbox is empty and the `Recent notes` region replaces the result list.
+- **CLI match.** Search from the terminal. Run `control-notes cli -- notes search "quarterly" --format json`. Exit code `0` and stdout contain one object whose title is `Quarterly plan`.
+- **CLI miss.** Search for an absent value. Run `control-notes cli -- notes search "volcano" --format json`. Exit code `0` and stdout are `[]`.
+- **Proof.** Capture the populated result state. Run `control-notes browser snapshot --aria --path artifacts/search/results.aria.txt` and `control-notes browser screenshot --path artifacts/search/results.png`. Both artifacts identify Notes, the query, and `Quarterly plan`.
+
+## Gotchas
+
+- Pressing `/` while the editor or searchbox has focus inserts text instead of opening search.
+- Results update after a short debounce. Wait for the results list or empty status, not a fixed sleep.
+- Archived notes are excluded unless the user enables `Include archived`.
+- The CLI defaults to human-readable output. Use `--format json` for stable assertions.
+- Opening a result changes browser state. Reopen search before proving another query.

package/plugin/skills/maintain-verification-skill/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/plugin/skills/maintain-verification-skill/README.md

@@ -0,0 +1,9 @@
+# maintain-verification-skill
+
+Periodic pass that keeps a project verification skill and feature map accurate against the source and the live app.
+
+Invoke with `/maintain-verification-skill`.
+
+## Origin
+
+Ported from [pstack](https://github.com/cursor/plugins/tree/main/pstack) by Lauren Tan (poteto), MIT licensed. The Cursor version routed work across Claude, GPT, and Grok through a Cursor rules file and used Cursor-only tooling. This port targets Claude Code: subagents use the Agent tool with Claude models (`opus`, `sonnet`, `fable`), paths use `.claude/`, and references to Cursor-only skills and plugins are removed or replaced.

package/plugin/skills/maintain-verification-skill/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: maintain-verification-skill
+description: "Periodic pass that keeps a project's verification skill and feature map honest: parallel source readers per feature, one live session driving every feature, at most one PR of proven corrections. Use for /maintain-verification-skill or \"audit the verify skill\"."
+disable-model-invocation: true
+---
+
+# Maintain a verification skill
+
+A feature map rots the moment the app changes. This skill is the upkeep loop for a skill generated by `/create-verification-skill` (or any project-local verification skill with a feature map). The unit of rigor is the feature, not every sentence: cover every feature file from source and exercise every feature live, without terminalising every bullet.
+
+## Outcomes
+
+Pick one, and say which:
+
+- **clean** — every feature got source and live coverage; nothing worth shipping. No branch, no PR.
+- **changed** — one PR ships proven doc, harness, or map corrections.
+- **blocked** — coverage could not finish or a proven fix could not ship safely. Say exactly what blocked it.
+
+## Edit scope
+
+Only edit the verification skill's own directory (its SKILL.md, features/, and any harness scripts it owns). Never edit product code during a run: a behavior the map describes that the app no longer does is either doc drift (fix the map) or a product regression (report it, don't paper over it in docs).
+
+## Pass
+
+0. **Locate the target.** Find the verification skill to maintain: the project-local skill whose body has launch/drive sections and a feature map (usually `.claude/skills/verify-*/`). Several candidates → ask which one (AskUserQuestion); none → stop and point at `/create-verification-skill` instead of inventing a target.
+
+1. **Index hygiene.** Read the feature map README and glob its sibling files. Fix missing, extra, duplicate, or dead entries. Lightweight; no generated inventory.
+
+2. **Source wave.** One read-only subagent per feature file, launched concurrently in one message (Agent tool, `subagent_type: "general-purpose"`, `model: "sonnet"`, `run_in_background: true`; the prompt says "Read-only. Do not edit, create, or delete files."). Each explains "how does this user-facing feature work?" from source, flags likely doc drift with citations, and returns one concise live-verification recipe. Children never drive the app and never edit files. Return shape: feature summary / source entry points / likely drift or none / one recipe.
+
+3. **Reconcile.** Every feature file has a returned summary. Merge overlapping recipes into as few app states as practical. Spot-check cited drift; don't re-prove clean claims. Sweep recent churn for user-facing surfaces missing from the map — require a concrete source path before calling one missing.
+
+4. **Live pass.** Required even when source looks clean. The coordinator owns all driving; follow the verification skill's own launch model — one long-lived instance driven serially for servers and UIs, or a fresh isolated session per drive for short-lived CLIs (the skill's Launch section decides, not this one). Exercise every feature at least once, and hold three invariants the whole pass, whatever the failure: (1) never drive an instance you haven't health-checked since it last did something surprising — doctor before first drive, doctor on each fresh session where sessions are the unit, doctor again after any failed drive, and where doctor can't see the failure (a wedged UI state on a healthy process), reset to a known state or relaunch rather than hoping; (2) evidence captured so far survives every cleanup, checked at its named location, not assumed; (3) nothing a drive started outlives that drive's usefulness — failed-iteration residue is cleaned whether the session is stuck, exited, or shared (for a shared instance, clean the residue, not the instance). A doctor failure caused by skill drift is drift: fix it under edit scope and retry once — restart whatever the fix invalidated, nothing more — before calling the pass `blocked`. A feature that can't be reached is `verified-unreachable` only with the concrete prerequisite (auth, entitlement, OS, external state) and the route attempted; if the map omits that prerequisite, that's drift. Any harness fix from triage gets re-driven live before it ships. Final teardown happens after the last drive of the run — including those re-proofs — so nothing outlives the run (evidence stays, per the skill).
+
+5. **Triage.** Wrong or missing user-POV description → doc drift, fix it. Working behavior the harness can't drive → harness gap, fix it; a harness fix follows the same helpers rule as generation (scripts executable, invocation documented in the skill body). App behavior that's actually broken → product gap; record it for the user, keep it out of this PR.
+
+6. **Ship or stop.** For changed: one PR of proven corrections, re-read every changed file first. For clean or blocked: no PR, report the outcome and the coverage honestly.
+
+Keep concise run notes (features covered, unreachable prerequisites, confirmed drift, outcome) in a scratch location; don't commit them.

package/plugin/skills/maintain-verification-skill/manifest.json

@@ -0,0 +1,23 @@
+{
+  "name": "maintain-verification-skill",
+  "type": "skill",
+  "version": "1.0.0",
+  "description": "Periodic pass that keeps a project verification skill and feature map accurate against the source and the live app.",
+  "author": "Jason Paff",
+  "entrypoint": "SKILL.md",
+  "files": [
+    "LICENSE"
+  ],
+  "tags": [
+    "pstack",
+    "verification",
+    "maintenance"
+  ],
+  "tools": [
+    "claude-code"
+  ],
+  "metadata": {
+    "upstream": "pstack by Lauren Tan (poteto), https://github.com/cursor/plugins, MIT",
+    "portedFrom": "cursor"
+  }
+}