@workerstack/repo 0.0.0-stage → 0.1.0

package/dist/presets/temp-root.constants.d.ts

@@ -0,0 +1,6 @@
+/** The errno code `process.kill(pid, 0)` throws when the pid exists but belongs to another user. */
+export declare const PERMISSION_DENIED = "EPERM";
+/** The name every run root starts with; `repo-test-<pid>-<suffix>` gives the pid of the run that made it. */
+export declare const ROOT_PREFIX = "repo-test-";
+/** The dir bun itself writes into TEMP when a child runs `node` through its shim (`bun-node-<hash>`); no test makes it. */
+export declare const BUN_SHIM_PREFIX = "bun-node-";

package/dist/presets/temp-root.constants.js

@@ -0,0 +1,6 @@
+/** The errno code `process.kill(pid, 0)` throws when the pid exists but belongs to another user. */
+export const PERMISSION_DENIED = "EPERM";
+/** The name every run root starts with; `repo-test-<pid>-<suffix>` gives the pid of the run that made it. */
+export const ROOT_PREFIX = "repo-test-";
+/** The dir bun itself writes into TEMP when a child runs `node` through its shim (`bun-node-<hash>`); no test makes it. */
+export const BUN_SHIM_PREFIX = "bun-node-";

package/dist/presets/temp-root.d.ts

@@ -0,0 +1,2 @@
+export declare function leakMessage(names: string[]): string;
+export declare function setup(): () => void;

package/dist/presets/temp-root.js

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readEnv } from "../cli/env.js";
+import { rootPath } from "./temp-root-env.js";
+import { BUN_SHIM_PREFIX, PERMISSION_DENIED } from "./temp-root.constants.js";
+/**
+ * Vitest globalSetup: every run gets its own temp root, so a test that leaves a dir behind fails the run and a
+ * crashed run's root is removed by the next one. `defineConfig` gives test processes the root as TMPDIR, TEMP and
+ * TMP (`rootEnv`); this process keeps the real temp dir, so its own tooling never counts as a leak.
+ */
+const FAILED = 1;
+/** `repo-test-<pid>` names give the pid; anything else is not ours. */
+function pidOf(name) {
+    const match = /^repo-test-(\d+)$/.exec(name);
+    return match?.[1] === undefined ? undefined : Number(match[1]);
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: the pid exists but belongs to someone else.
+        return error instanceof Error && "code" in error && error.code === PERMISSION_DENIED;
+    }
+}
+/** Removes the roots whose run is gone; a second call finds nothing and does nothing. */
+function removeDeadRoots(base) {
+    for (const name of fs.readdirSync(base)) {
+        const pid = pidOf(name);
+        if (pid !== undefined && !isAlive(pid))
+            fs.rmSync(path.join(base, name), { recursive: true, force: true });
+    }
+}
+export function leakMessage(names) {
+    const list = names.sort().join(", ");
+    const noun = names.length === 1 ? "entry" : "entries";
+    return `tests left ${names.length} ${noun} in the run's temp root: ${list}; remove each in the test that made it`;
+}
+/** Ends the run: keeps the root when asked, otherwise removes it and fails when it was not empty. */
+function finish(root) {
+    if (readEnv().REPO_E2E_KEEP) {
+        process.stdout.write(`kept temp root: ${root}\n`);
+        return;
+    }
+    const left = fs.readdirSync(root).filter((name) => !name.startsWith(BUN_SHIM_PREFIX));
+    fs.rmSync(root, { recursive: true, force: true });
+    if (left.length === 0)
+        return;
+    process.exitCode = FAILED;
+    process.stderr.write(`Error: ${leakMessage(left)}\n`);
+}
+export function setup() {
+    const root = rootPath();
+    removeDeadRoots(path.dirname(root));
+    // A live pid's root is this run's own; one left by an earlier process with the same pid is stale.
+    fs.rmSync(root, { recursive: true, force: true });
+    fs.mkdirSync(root);
+    return () => finish(root);
+}

package/dist/presets/vitest.constants.d.ts

@@ -0,0 +1,16 @@
+/** The wrangler files a Worker package may have, in the order the preset looks for them. */
+export declare const WRANGLER_FILES: readonly ["wrangler.jsonc", "wrangler.json", "wrangler.toml"];
+/** The package that runs tests in the Workers runtime. */
+export declare const PLUGIN_PACKAGE = "@cloudflare/vitest-plugin";
+/** The plugin range the preset is written against. */
+export declare const PLUGIN_RANGE = "^1.6.0";
+/** The prefix every message from the preset starts with. */
+export declare const MESSAGE_PREFIX = "@workerstack/repo/vitest";
+/** The guard module's name, without the extension of the module that points at it. */
+export declare const GUARD_NAME = "temp-root";
+/** The package the guard loads in the runner process, which vitest must inline there. */
+export declare const INLINED_PACKAGE = "zod";
+/** The error code `import()` gives a package it cannot find. */
+export declare const NOT_FOUND = "ERR_MODULE_NOT_FOUND";
+/** The question vite ends its error with when a bare import resolves to no installed package. */
+export declare const NOT_INSTALLED = "Is it installed?";

package/dist/presets/vitest.constants.js

@@ -0,0 +1,16 @@
+/** The wrangler files a Worker package may have, in the order the preset looks for them. */
+export const WRANGLER_FILES = ["wrangler.jsonc", "wrangler.json", "wrangler.toml"];
+/** The package that runs tests in the Workers runtime. */
+export const PLUGIN_PACKAGE = "@cloudflare/vitest-plugin";
+/** The plugin range the preset is written against. */
+export const PLUGIN_RANGE = "^1.6.0";
+/** The prefix every message from the preset starts with. */
+export const MESSAGE_PREFIX = "@workerstack/repo/vitest";
+/** The guard module's name, without the extension of the module that points at it. */
+export const GUARD_NAME = "temp-root";
+/** The package the guard loads in the runner process, which vitest must inline there. */
+export const INLINED_PACKAGE = "zod";
+/** The error code `import()` gives a package it cannot find. */
+export const NOT_FOUND = "ERR_MODULE_NOT_FOUND";
+/** The question vite ends its error with when a bare import resolves to no installed package. */
+export const NOT_INSTALLED = "Is it installed?";

package/dist/presets/vitest.d.ts

@@ -0,0 +1,11 @@
+import { type UserWorkspaceConfig, type ViteUserConfig } from "vitest/config";
+/** A package's vitest project: the shared timeouts and the forks pool, or the Workers runtime beside a wrangler file. */
+export declare function defineProject(config: UserWorkspaceConfig): UserWorkspaceConfig;
+/**
+ * A root vitest config: the project defaults plus istanbul coverage, overridden by `config`. The floors file
+ * (`coverage-floors.json` in the cwd, or `options.floors`) becomes per-file coverage thresholds; the caller's own
+ * thresholds are merged over them, and a missing file adds none.
+ */
+export declare function defineConfig(config: ViteUserConfig, options?: {
+    floors?: string;
+}): ViteUserConfig;

package/dist/presets/vitest.js

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { mergeConfig } from "vitest/config";
+import { rootEnv } from "./temp-root-env.js";
+import { GUARD_NAME, INLINED_PACKAGE, WRANGLER_FILES } from "./vitest.constants.js";
+import { workersPlugin } from "./workers-plugin.js";
+/** Where `defineConfig` looks for the per-file floors `repo coverage` writes, relative to the cwd. */
+const DEFAULT_FLOORS = "coverage-floors.json";
+/** The temp root guard beside this module, with this module's own extension: `.ts` from source, `.js` from dist. */
+function guardPath() {
+    const self = fileURLToPath(import.meta.url);
+    return path.join(path.dirname(self), `${GUARD_NAME}${path.extname(self)}`);
+}
+/** The project root vitest will use: the config's own, else the cwd. */
+function rootOf(config) {
+    return path.resolve(config.test?.root ?? config.root ?? process.cwd());
+}
+/** The first wrangler file in `root`, or none for a package that is not a Worker. */
+function wranglerFile(root) {
+    return WRANGLER_FILES.find((name) => fs.existsSync(path.join(root, name)));
+}
+// A Windows runner spawns bun and git 25-35x slower than Linux. The platform is read per call, not at module
+// load, so one OS can exercise both branches.
+function projectDefaults(config) {
+    const timeout = process.platform === "win32" ? 60_000 : 5_000;
+    const root = rootOf(config);
+    const file = wranglerFile(root);
+    // Bun module namespaces carry `__esModule`, so vitest's default interop would swap a namespace for its default.
+    const test = { testTimeout: timeout, hookTimeout: timeout, deps: { interopDefault: false } };
+    if (file === undefined)
+        return { test: { ...test, pool: "forks" } };
+    // The Workers pool is the plugin's; a forks default would take the tests back to node.
+    const configPath = path.join(root, file);
+    return { plugins: [workersPlugin(configPath)], test };
+}
+/** A package's vitest project: the shared timeouts and the forks pool, or the Workers runtime beside a wrangler file. */
+export function defineProject(config) {
+    return mergeConfig(projectDefaults(config), config);
+}
+/** The floors file's per-file thresholds, or none when the file is absent. */
+function readFloors(file) {
+    const full = path.resolve(file);
+    if (!fs.existsSync(full))
+        return {};
+    try {
+        const floors = JSON.parse(fs.readFileSync(full, "utf8"));
+        return floors /* the floors file holds the thresholds object repo coverage wrote */;
+    }
+    catch {
+        throw new Error(`${full} is not valid JSON; run \`bun repo coverage\` to write it again`);
+    }
+}
+/**
+ * A root vitest config: the project defaults plus istanbul coverage, overridden by `config`. The floors file
+ * (`coverage-floors.json` in the cwd, or `options.floors`) becomes per-file coverage thresholds; the caller's own
+ * thresholds are merged over them, and a missing file adds none.
+ */
+export function defineConfig(config, options = {}) {
+    const thresholds = readFloors(options.floors ?? DEFAULT_FLOORS);
+    const coverage = { provider: "istanbul", ...(Object.keys(thresholds).length > 0 ? { thresholds } : {}) };
+    // The guard loads cli/env.ts in the runner process, where an external zod loses its named exports.
+    const guard = { globalSetup: [guardPath()], server: { deps: { inline: [INLINED_PACKAGE] } }, coverage };
+    // Only test processes get the root: the runner's own tooling (miniflare) makes and removes temp dirs of its own.
+    const defaults = mergeConfig(projectDefaults(config), { test: { ...guard, env: rootEnv() } });
+    return mergeConfig(defaults, config);
+}

package/dist/presets/workers-plugin.d.ts

@@ -0,0 +1,10 @@
+import type { ViteUserConfig } from "vitest/config";
+type Plugin = Exclude<NonNullable<ViteUserConfig["plugins"]>[number], Promise<unknown>>;
+/**
+ * The Workers plugin for the wrangler file at `configPath`, as a promise vite settles while it resolves the config;
+ * the plugin is ESM only, so a synchronous `require` cannot load it. A plugin that is not installed becomes the line
+ * that says how to install it, naming the wrangler file; a module without `cloudflareTest` is an error naming the
+ * expected range; any other load error passes through unchanged.
+ */
+export declare function workersPlugin(configPath: string, load?: () => Promise<unknown>): Promise<Plugin>;
+export {};

package/dist/presets/workers-plugin.js

@@ -0,0 +1,54 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import path from "node:path";
+import { MESSAGE_PREFIX, NOT_FOUND, NOT_INSTALLED, PLUGIN_PACKAGE, PLUGIN_RANGE } from "./vitest.constants.js";
+const installHint = `bun add -d ${PLUGIN_PACKAGE}`;
+/**
+ * True for the error `import()` gives when the plugin itself, not one of its own dependencies, is not installed:
+ * node and bun give a code, and vite's module runner, which loads the preset under vitest, says so in the message.
+ */
+function isPluginMissing(error) {
+    if (!(error instanceof Error) || !error.message.includes(PLUGIN_PACKAGE))
+        return false;
+    return ("code" in error && error.code === NOT_FOUND) || error.message.includes(NOT_INSTALLED);
+}
+function hasCloudflareTest(loaded) {
+    return (typeof loaded === "object" &&
+        loaded !== null &&
+        "cloudflareTest" in loaded &&
+        typeof loaded.cloudflareTest === "function");
+}
+/** The plugin package, imported from the preset's own resolution scope, where an optional peer is linked. */
+function importPlugin() {
+    const specifier = PLUGIN_PACKAGE;
+    return import(__rewriteRelativeImportExtension(specifier));
+}
+/**
+ * The Workers plugin for the wrangler file at `configPath`, as a promise vite settles while it resolves the config;
+ * the plugin is ESM only, so a synchronous `require` cannot load it. A plugin that is not installed becomes the line
+ * that says how to install it, naming the wrangler file; a module without `cloudflareTest` is an error naming the
+ * expected range; any other load error passes through unchanged.
+ */
+export async function workersPlugin(configPath, load = importPlugin) {
+    let loaded;
+    try {
+        loaded = await load();
+    }
+    catch (error) {
+        if (!isPluginMissing(error))
+            throw error;
+        const file = path.basename(configPath);
+        throw new Error(`${MESSAGE_PREFIX}: ${file} is here, so tests run in the Workers runtime; ${installHint}`, {
+            cause: error,
+        });
+    }
+    if (!hasCloudflareTest(loaded))
+        throw new Error(`${MESSAGE_PREFIX}: ${PLUGIN_PACKAGE} does not export cloudflareTest; ${installHint}@${PLUGIN_RANGE}`);
+    return loaded.cloudflareTest({ wrangler: { configPath } });
+}

package/package.json

@@ -1,6 +1,143 @@
 {
   "name": "@workerstack/repo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "private": false,
+  "description": "Agent workflow, code standards, gates, workspace and docs checks for workerstack repos",
+  "keywords": [
+    "agents",
+    "workerstack",
+    "monorepo",
+    "lint",
+    "ci"
+  ],
+  "homepage": "https://github.com/workerstack/repo",
+  "bugs": {
+    "url": "https://github.com/workerstack/repo/issues"
+  },
+  "license": "MIT",
+  "author": "workerstack",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/workerstack/repo.git"
+  },
+  "bin": {
+    "repo": "./bin/repo.ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./cli/config.ts",
+      "default": "./cli/config.ts"
+    },
+    "./tsconfig/*": "./tsconfig/*.json",
+    "./agents/*": "./agents/*",
+    "./lint": "./cli/lint/index.ts",
+    "./vitest": {
+      "types": "./dist/presets/vitest.d.ts",
+      "default": "./dist/presets/vitest.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin/repo.ts",
+    "cli",
+    "!cli/sync/fixtures/consumer",
+    "!cli/sync/fixtures/consumer-stock",
+    "!cli/sync/fixtures/golden",
+    "references",
+    "tsconfig",
+    "dist/presets/*.js",
+    "dist/presets/*.d.ts",
+    "dist/cli/env*.js",
+    "dist/cli/env*.d.ts",
+    "agents",
+    "!cli/scripts/**/*.test.ts",
+    "!cli/lint/**/*.test.ts",
+    "!cli/scripts/fixtures",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "@oxlint/plugins": "1.92.0",
+    "@total-typescript/ts-reset": "^0.6.1",
+    "@types/bun": "^1.4.4",
+    "cross-spawn": "^7.0.6",
+    "jsonc-parser": "^3.3.1",
+    "knip": "6.43.0",
+    "oxc-parser": "0.157.0",
+    "oxfmt": "0.77.0",
+    "oxlint": "1.92.0",
+    "oxlint-tsgolint": "7.0.2006",
+    "smol-toml": "^1.8.0",
+    "typescript": "^5.9.3",
+    "yaml": "2.9.1",
+    "zod": "^4.6.7"
+  },
+  "peerDependencies": {
+    "@cloudflare/vitest-plugin": "^1.6.0",
+    "@cloudflare/workers-types": ">=4",
+    "@stryker-mutator/core": "10.1.1",
+    "@stryker-mutator/vitest-runner": "10.1.1",
+    "@vitest/coverage-istanbul": "^5.1.0",
+    "vitest": "^5.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@cloudflare/vitest-plugin": {
+      "optional": true
+    },
+    "@cloudflare/workers-types": {
+      "optional": true
+    },
+    "@stryker-mutator/core": {
+      "optional": true
+    },
+    "@stryker-mutator/vitest-runner": {
+      "optional": true
+    },
+    "@vitest/coverage-istanbul": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "prepare": "bun ./dev/link-self.ts",
+    "build": "bun --bun tsc -p tsconfig.build.json",
+    "prepack": "bun run build",
+    "doctor": "repo doctor",
+    "clean": "repo clean",
+    "setup": "repo setup",
+    "tasks": "repo tasks",
+    "yolo": "repo yolo",
+    "yolo:check": "repo yolo --check",
+    "purge:global-mcps": "repo purge-mcps",
+    "purge:global-mcps:apply": "repo purge-mcps --apply",
+    "typecheck": "bun --bun tsc -p .",
+    "lint": "bun ./bin/repo.ts lint",
+    "fmt": "bun ./bin/repo.ts fmt",
+    "test": "bun --bun vitest run",
+    "ci": "bun ./bin/repo.ts ci",
+    "test:e2e": "bun --bun vitest run -c vitest.e2e.config.ts"
+  },
+  "devDependencies": {
+    "@stryker-mutator/core": "10.1.1",
+    "@stryker-mutator/vitest-runner": "10.1.1",
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^24.13.3",
+    "@vitest/coverage-istanbul": "^5.1.0",
+    "tar": "^7.5.22",
+    "verdaccio": "^6.10.5",
+    "vitest": "^5.1.0"
+  },
+  "engines": {
+    "bun": ">=1.4.4"
+  },
+  "packageManager": "bun@1.4.4"
+}

package/references/INDEX.md

@@ -0,0 +1,100 @@
+# Law
+
+Protocol stays overview; domain fills this.
+
+## Skills naming
+
+Do not reuse a repo skill name for a consumer custom skill: a repo-owned skill of the same name in `.repo/skills/` replaces the stock one. Pack names stay reserved when their directory is absent.
+
+`bun repo sync` links the stock skills from the installed package into each host tree and writes the rest; it never copies stock references or scripts. doctor/listen/speak call the consumer's root `scripts/lib/env.mjs` `loadEnv` when that file exists.
+
+Upgrading is bumping `@workerstack/repo` in `package.json` and running `bun install`: the postinstall sync regenerates every tree from the new package. The first sync in a repo an older `bun repo init` copied moves your own rules, subagents, skills, settings keys, lessons, hooks and references into `.repo/` and `references/`, untracks the generated paths, removes the copied `.rulesync/`, and prints one moved line per move. Commit the result. There is no upgrade command.
+
+<!-- repo:skills -->
+| name | origin | description | task | commandPath | refs |
+| --- | --- | --- | --- | --- | --- |
+| ask | repo | Session flag. Finish one step, recap, then ask before the next. |  |  |  |
+| auto | repo | >- |  |  |  |
+| away | repo | Session flag. Nobody is watching: decide instead of asking, log each choice, keep going. |  |  |  |
+| blast-radius | repo | >- |  |  |  |
+| bro | repo | Restate the last message in plain human language, with no jargon. |  |  |  |
+| browser | repo | >- |  |  |  |
+| clasp | repo | >- |  |  |  |
+| commit | repo | Inspect the diff and commit with a Conventional Commits subject line. Use for /commit, "commit this", "commit these cha… |  |  |  |
+| commit-and-push | repo | Alias of commit-push (1-release stub). Use for /commit-and-push, "commit and push", "commit this and push". Must push.… |  |  |  |
+| commit-push | repo | Commit with a Conventional Commits subject, then push. Use for /commit-push, "commit and push", "commit this and push".… |  |  |  |
+| commit-push-deploy | repo | Commit, push, then deploy only if allowlisted infra already exists. Use for /commit-push-deploy, "commit push deploy",… |  |  |  |
+| commit-push-release | repo | Commit, push, and for "release" run `bun repo release` from the main checkout (it bumps, stamps CHANGELOG.md, pushes, w… |  |  |  |
+| correct | repo | >- |  |  |  |
+| do | repo | Do a small task now: no plan, no review. Worktree, nearest test and commit still apply. |  |  |  |
+| explain | repo | Longer human recap this reply only. |  |  |  |
+| google-workspace | repo | >- |  |  |  |
+| handoff | repo | Write a session handoff under .tmp/repo/handoffs/. Continue with /pickup. |  |  |  |
+| implement-plan | repo | Execute remaining leaves in a .tmp/repo/plans checklist. Skip [x]. |  |  |  |
+| implement-roadmap | repo | >- |  |  |  |
+| jev | repo | >- |  |  |  |
+| listen | repo | >- |  |  |  |
+| pickup | repo | Continue a handoff under .tmp/repo/handoffs/. |  |  |  |
+| principle-attack-the-premise | repo | >- |  |  |  |
+| principle-boundary-discipline | repo | >- |  |  |  |
+| principle-build-the-lever | repo | >- |  |  |  |
+| principle-encode-lessons-in-structure | repo | >- |  |  |  |
+| principle-exhaust-the-design-space | repo | >- |  |  |  |
+| principle-experience-first | repo | >- |  |  |  |
+| principle-explain-the-number | repo | >- |  |  |  |
+| principle-fix-root-causes | repo | >- |  |  |  |
+| principle-foundational-thinking | repo | >- |  |  |  |
+| principle-guard-the-context-window | repo | >- |  |  |  |
+| principle-laziness-protocol | repo | >- |  |  |  |
+| principle-make-operations-idempotent | repo | >- |  |  |  |
+| principle-migrate-callers-then-delete-legacy-apis | repo | >- |  |  |  |
+| principle-minimize-reader-load | repo | >- |  |  |  |
+| principle-model-the-domain | repo | >- |  |  |  |
+| principle-never-block-on-the-human | repo | >- |  |  |  |
+| principle-outcome-oriented-execution | repo | >- |  |  |  |
+| principle-prove-it-works | repo | >- |  |  |  |
+| principle-redesign-from-first-principles | repo | >- |  |  |  |
+| principle-separate-before-serializing-shared-state | repo | >- |  |  |  |
+| principle-sequence-verifiable-units | repo | >- |  |  |  |
+| principle-subtract-before-you-add | repo | >- |  |  |  |
+| principle-test-behavior-not-implementation | repo | >- |  |  |  |
+| principle-type-system-discipline | repo | >- |  |  |  |
+| review-plan | repo | Review a plan in a fresh agent before approval. Use for /review-plan. |  |  |  |
+| review-roadmap | repo | Review a roadmap in a fresh agent before lock. Use for /review-roadmap. |  |  |  |
+| show-me | repo | Restate the current proposal as a concrete before and after: commands, output, errors, files. |  |  |  |
+| speak | repo | >- |  |  |  |
+| su | repo | Short status update: done, next, and blockers or on-track ETA. |  |  |  |
+| teach | repo | >- |  |  |  |
+| tmp | repo | Dump a one-off convo artifact under .tmp/repo/. |  |  |  |
+| typescript-best-practices | repo | >- |  |  |  |
+| unslop | repo | Cut AI tells from any writing. Use for /unslop. |  |  |  |
+| write-plan | repo | Write a local checklist under .tmp/repo/plans/. Then /implement-plan {n}. |  |  |  |
+| write-roadmap | repo | >- |  |  |  |
+<!-- /repo:skills -->
+
+<!-- repo:refs -->
+| path | title | tags | summary |
+| --- | --- | --- | --- |
+| node_modules/@workerstack/repo/references/browser.md | Browser | browser | Zero-config in-tree session rail. Not MCP. Not env. Not raw Playwright. Lightpanda first; swap to Chromium when blocked. |
+| node_modules/@workerstack/repo/references/cascade.md | Protocol | cascade | The session agent has tools. Fat Read/Grep/Bash dumps are rewritten to `<root>/node_modules/.bin/repo job` (squeez + st… |
+| node_modules/@workerstack/repo/references/clasp.md | Clasp | clasp | Low-level Apps Script CLI. Optional. Doctor reports it. |
+| node_modules/@workerstack/repo/references/cloudflare.md | Cloudflare | cloudflare | Use `cf` for every Cloudflare task. Do not run `wrangler` yourself and do not add it to a project that has none. |
+| node_modules/@workerstack/repo/references/google-workspace.md | google-workspace | google-workspace | Create and edit Google Sheets, Docs, Slides, Calendar events, and Gmail from the session. |
+| node_modules/@workerstack/repo/references/hooks.md | Hooks | hooks | SessionStart carries only the folder map: Claude / Codex run the `session-map` hook, which injects the code-only map `b… |
+| node_modules/@workerstack/repo/references/implementation-format.md | Implementation format (SSOT) |  | Local session journal for `/implement-plan`. Not a plan, handoff, or git commit. |
+| node_modules/@workerstack/repo/references/jev.md | Jev | jev | Closed external decision. The source text is already saved. The question is a yes/no or a named choice. One call. Not o… |
+| node_modules/@workerstack/repo/references/lessons.md | Lessons | lessons | Mistakes that outlive one task. One committed file per mistake under `.repo/lessons/`, with a generated index. Not host… |
+| node_modules/@workerstack/repo/references/listen.md | Listen | listen | Speech-to-text from the session. Input only. Not TTS. Not a live voice agent. Not MCP. |
+| node_modules/@workerstack/repo/references/map.md | Map | map | Cheap outline. Not a file dump. |
+| node_modules/@workerstack/repo/references/output.md | Output | output | en-US default. Detail behind the reply rules in `overview.md`, which stays the source for voice and shape. |
+| node_modules/@workerstack/repo/references/plan-format.md | Plan format (SSOT) |  | Local session checklist. Not a design doc, PR stack, or DAG. |
+| node_modules/@workerstack/repo/references/review-loop.md | Review loop | review-loop | Read this when the plan's `strategy` is `review-fast` or `review-deep`. You are the reviewer. An implementer agent writ… |
+| node_modules/@workerstack/repo/references/roadmap-format.md | Roadmap format (SSOT) |  | Ordered program of child plans. Not a plan, a handoff, or a design doc. |
+| node_modules/@workerstack/repo/references/rtk.md | RTK | rtk | Shell stdout compression. PreToolUse: Bash → `rtk <cmd>`. Not Read/Grep/Glob/prompts/images. |
+| node_modules/@workerstack/repo/references/scope.md | Scope | scope | Plan by default. A straight shot is the exception. The plan caps the result, so its depth scales with the work. This fi… |
+| node_modules/@workerstack/repo/references/setup.md | Setup | setup | Handheld machine setup for optional integrations. Any OS. Secrets stay in `~/.workerstack/` (Windows `%USERPROFILE%\.wo… |
+| node_modules/@workerstack/repo/references/speak.md | Speak | speak | Text-to-speech from the session. Output only. Not STT. Not a mic. Not MCP. Speech-to-text is `/listen`: `node_modules/@… |
+<!-- /repo:refs -->
+
+<!-- repo:stack -->
+<!-- /repo:stack -->

package/references/browser.md

@@ -0,0 +1,66 @@
+---
+tags: [browser]
+---
+
+# Browser
+
+Zero-config in-tree session rail. Not MCP. Not env. Not raw Playwright. Lightpanda first; swap to Chromium when blocked.
+
+```
+bun repo browser nav|snap|click|fill|scroll|wait|hover|select|shot|pdf|stop|doctor|ensure
+```
+
+Default engine: **Lightpanda** (`lightpanda` on PATH). Chromium when a rule below requires it. Never report "can't browse" while Chromium is available.
+
+## Verbs
+
+| verb | purpose |
+| --- | --- |
+| `nav <url>` | launch or reuse session; go to URL |
+| `snap` | markdown + numbered AX refs (default read) |
+| `click <ref>` | click a ref from last `snap` |
+| `fill <ref> <text>` | fill a ref from last `snap` |
+| `scroll [ref|down|up|N]` | scroll a snap ref into view, or the window |
+| `wait [ms]` | pause (default 1000, cap 15000) |
+| `hover <ref>` | hover a snap ref |
+| `select <ref> <value>` | set a select/option value |
+| `shot` | screenshot (Chromium paint) |
+| `pdf` | PDF (Chromium paint) |
+| `stop` | reap engine pid; clear session; idempotent |
+| `doctor` | unified prereq doctor (`bun repo doctor`); alias `ensure` |
+| `ensure` | alias of `doctor` |
+
+Session + profile + artifacts: `.tmp/repo/browser/` only.
+
+## Install
+
+Run `bun repo doctor`. Handheld engine hints (no keys): `bun repo setup browser`. Doctor/setup is enough. Do not read a README unless those are missing; then https://github.com/workerstack/repo#prerequisites (not the consumer README).
+
+## Engine
+
+Lightpanda first (`lightpanda serve` internally, CDP, `LP.getMarkdown` + AX refs).
+
+Chromium immediately when any of:
+
+- verb is `shot` | `pdf` | `trace`
+- `process.platform === "win32"`
+- Chromium-first host: figma, Google docs / sheets / slides, mail.google, earth, amazon
+- `lightpanda` missing from PATH and a Chromium binary is present
+- Lightpanda probe fails **once** → one Chromium replay of last URL; no loop
+- `snap` on Lightpanda is empty, a bot/JS wall, or client-rendered junk → one Chromium replay, then snap again
+
+The session agent does not invent a "can't" for Amazon or other client-rendered sites. The rail swaps. One swap cap. App e2e stays Playwright (`playwright test`), not this CLI.
+
+No user env. Never `REPO_BROWSER*`. Never `LIGHTPANDA_CDP_URL`.
+
+## Non-goals
+
+- MCP browser servers
+- user env knobs
+- raw Playwright as the browse tool (Playwright is the app e2e runner)
+- repo `job:browse`
+- teaching thinker / orchestrator to browse
+
+## RTK
+
+`playwright` on the RTK command list is the **test-runner family only**. Browser rail is `lightpanda` + `bun repo browser`.

package/references/cascade.md

@@ -0,0 +1,15 @@
+---
+tags: [cascade]
+---
+
+# Protocol
+
+The session agent has tools. Fat Read/Grep/Bash dumps are rewritten to `<root>/node_modules/.bin/repo job` (squeez + stash). Isolation facts stay ≤8 lines.
+
+Run `bun repo job --job search|exec|slice|fetch|test` first. Spawn scout when the dump needs judgment (browse snap, messy test log) and the return is a short isolation fact; spawn researcher for heavy web or browser research that returns facts with sources. Use a host agent or a fan-out when that split is cheaper for the task, or when the user asks for it.
+
+`need:` JSON (search|exec|slice|fetch) may be intercepted in-hook (cap 4). Peek/kill if a child is running: Grok `get_command_or_subagent_output` `timeout_ms=60000`. Other hosts: block on spawn return.
+
+Session flags: `/auto` (default) keeps going and asks on blockers instead of monkey-patching. `/ask` finishes one step, recaps, then asks. `/away` decides instead of asking and logs each choice as a `- decision:` entry in the plan. Slash `/ask` or `/away` stamps `.tmp/repo/orchestrator-logs/session-gate-{sid}` with `ask` or `away`; `/auto` unlinks either stamp. A plan or roadmap `mode:` wins over the flag.
+
+Scratch: `.tmp/repo/`. Stash: `.tmp/repo/stash/`. Sessions: `.tmp/repo/sessions/{sid}/`. Browser: `.tmp/repo/browser/`.

package/references/clasp.md

@@ -0,0 +1,21 @@
+---
+tags: [clasp]
+---
+
+# Clasp
+
+Low-level Apps Script CLI. Optional. Doctor reports it.
+
+For create/edit sheet, doc, slide, meeting, or mail, use **google-workspace**: `node_modules/@workerstack/repo/references/google-workspace.md` and `bun repo google-workspace`. Do not start from clasp.
+
+```
+bun add -g @google/clasp
+clasp login
+clasp create --type standalone --title <name>
+clasp pull
+clasp push
+clasp run <function>
+clasp status
+```
+
+Script files live next to `appsscript.json`. Git tracks them. `clasp run` needs the Apps Script API and an API-executable deployment. That path is for custom `.gs`, not day-to-day Workspace.