@workerstack/repo 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-10
+
+### Added
+
+- `workerstack.config.ts` with `defineConfig` from `@workerstack/repo` declares a repo's packs, and an unknown key or pack fails with a message that names it. `repo sync` writes `bunfig.toml` (hoisted linker, and no auto-install, so a missing import fails instead of fetching from the registry), the `# >>> @workerstack/repo` block in `.gitignore`, and the `repo:packages` and `repo:stack` sections of `references/INDEX.md`. It checks everything before writing anything and refuses to overwrite a hand-written `bunfig.toml`. `repo sync --check` fails on drift, and `repo sync --postinstall` prints errors without failing the install. `repo init` writes `workerstack.config.ts` when it is missing and adds `repo sync --postinstall` to the `postinstall` script.
+- Strict tsconfig bases with ts-reset built in: extend `@workerstack/repo/tsconfig/base`, `bun`, `worker` or `web` and list your sources under `include`. `JSON.parse`, `.json()` and similar calls then return `unknown` instead of `any`. The `bun` base brings Bun's types with it. The `worker` base needs `@cloudflare/workers-types` installed in your repo.
+- A shared vitest preset: `defineProject` for a package's `vitest.config.ts` and `defineConfig` for a root config, both from `@workerstack/repo/vitest`. They set 5s test and hook timeouts (60s on Windows) and the forks pool, and `defineConfig` adds istanbul coverage. Both set `deps.interopDefault: false`, which bun needs to import packages like zod. Your own settings win. Install `vitest` and, for coverage, `@vitest/coverage-istanbul` (both ^5.1.0), and run the tests with `bun --bun vitest`.
+- `repo check` now also fails when a tsconfig drops ts-reset: one that sets `files`, which replaces the base's, or one that extends no base. It prints one line per file and exits 1. A solution-style root with `"files": []` and `references` passes. The `repo` command now runs on bun, so bun must be on your PATH.
+- `repo release [--stable | --pre <id>]` releases the root package of a public repo with the `release` pack. It bumps the version from the Conventional Commits since the last tag (from 1.0 a breaking commit is a major, a feat a minor, a fix, perf or revert a patch; below 1.0 a breaking commit is a minor and the rest are patches), moves `## [Unreleased]` in CHANGELOG.md under the new version, commits `chore: release <name>@<version>`, pushes, waits on CI for that commit and only then tags `<name>@<version>` and pushes the tag. Run it again after a red or missing CI result: it finishes the same version, folding new Unreleased entries into it, instead of bumping twice. It refuses with one line, before writing anything, on a dirty tree, another branch, a main that differs from origin, a missing gh login, nothing to release, an empty Unreleased, a private package, a 1.x `--stable` and a tag that exists.
+- `repo release wait <name>@<version>` polls npm every 10 seconds for up to 15 minutes and prints `published <version> under <tag>`, or `published <version>` when no dist-tag points at it.
+- `repo check` holds a public root's CHANGELOG.md to Keep a Changelog: a dated `## [x.y.z] - YYYY-MM-DD` heading, the six section names, versions newest first and an `## [Unreleased]` section.
+- The commit-msg hook refuses a feat, fix, perf or breaking commit that stages a file of a public package without staging that package's CHANGELOG.md.
+- `repo sync` checks every output against its format, and the `.repo/` directory against its closed layout, schemas, links and size budget, before it writes anything, and then writes all of it or none. It also writes `.gitattributes` (generated files marked `linguist-generated`) and the editor settings that make them read-only, and refuses a nested ignore file. A rule can be scoped to `paths`, and an override has to replace a stock rule, subagent or skill. Each workspace package gets its own agents file, scoped rules, nested skills and a dependency index.
+- `repo sync` writes `.oxlintrc.json` and `.oxfmtrc.jsonc`, and `repo lint` and `repo fmt` run them. The lint plugin refuses module side effects, boundary breaks, magic numbers and untyped compared strings, an `as` cast without a reason, a file whose name does not match its export, an unticketed todo, commented-out code, a mock of the module under test and a v8 ignore. `lint.skip` in `workerstack.config.ts` records a reasoned exception and fails when it goes stale. The counts the lint finds are held in `.repo/lint-baseline.json`, which can only shrink. `repo check` refuses rule-disable and ts-ignore comments, a manifest with a wrong `private`, `sideEffects` or unpinned bun version, environment reads outside `cli/env.ts`, and a tsconfig that no gate runs. A strict `src` tsconfig is typechecked, `reject.ts` type tests run, and each exported type guard needs a test that rejects.
+- `repo turn` runs the gates for one change, and the generated `.githooks/pre-commit` and `.githooks/commit-msg` run it and check commit scopes and size against the `commit` limits in `workerstack.config.ts`. A feat or fix commit is refused unless a changed test fails without its source change. Test-run floors, known failures and the lint baseline are ratcheted against main, and a floor is raised and never lowered. A test run fails when it leaves a temp dir behind or skips a test for a reason that is not the platform.
+- `repo ci` runs every gate in one call, and `repo check` refuses a root script that chains them. `repo check` also runs knip from a generated config, where each `knip.ignore` entry carries a reason and fails when stale, and runs actionlint. Under the release pack `repo sync` writes `.github/workflows/ci.yml` with pinned actions: it tests on three operating systems, checks every pushed commit and compares each OS's skips, and `repo ci wait` waits for the run of HEAD. `repo mutate` runs Stryker under bun in a throwaway clone with score floors, and `repo sync` writes `.github/workflows/nightly.yml` with sharded mutation floors and your live tests. `repo persist` saves temp files into the repo.
+- With the `release` pack and `"private": false`, `repo sync` writes `.github/workflows/release.yml`. A `<name>@*` tag push, or `gh workflow run release.yml -f tag=<name>@<version>`, runs three jobs on that tag. `gate` checks that the tag equals the version in package.json at the tagged commit, that CHANGELOG.md has that version's section, that the commit is on the default branch and that its CI passed. `publish` packs with `bun pm pack`, refuses a packed `catalog:` or `workspace:` version, skips a version npm already serves and publishes through npm trusted publishing with no npm token, under `next` for a prerelease. `github` creates the GitHub release from the changelog section. A hand-written `release.yml` is refused. The jobs are also commands: `repo release gate | pack | publish | github <name>@<version>`, and `repo release help` lists them. A package that is not on npm yet cannot publish from CI; `publish` prints the steps: `npm login`, `bun repo release publish <name>@<version>` at the tag on your machine, then add the trusted publisher.
+
+### Changed
+
+- `repo doctor` no longer has a `node` row or node install hints, and `@workerstack/repo` no longer lists node in `engines`: nothing in it needs node. Bun is the only runtime it checks.
+- Agents can remove any managed worktree and delete any `wt/*` branch; the gate guards only the default branch and force pushes.
+- **Breaking:** the agent trees are generated and ignored. `repo sync` builds `AGENTS.md`, `.mcp.json`, `.claude/`, `.codex/`, `.agents/`, `.grok/` and `.cursor/` from `node_modules/@workerstack/repo` plus your `.repo/` into a staging dir, writes them, records them in `.repo/tmp/sync.json` and removes what drops out; in a consumer they are gitignored and every `bun install` recreates them (this repo still commits its own). `.repo/` holds the repo's own content: `rules/`, `subagents/`, `skills/`, `lessons/` (moved from `.rulesync/lessons/`), `settings/claude.json`, `hooks.jsonc`, `mcp-policy.jsonc` and `permissions.json`. `agents.hosts` in `workerstack.config.ts` picks the hosts to generate for (default: all five), and `agents.skills` enables the optional skills `google-workspace`, `listen`, `speak` and `clasp`, replacing `.rulesync/repo.features.jsonc`. `repo init` copies nothing: it writes `workerstack.config.ts` and `package.json`, then installs. The first `repo sync` in a repo an older init copied moves your own rules, subagents, skills, settings keys, `AGENTS.md` text, lessons, references, hooks, MCP policy and packs into `.repo/`, `references/` and `agents.skills`, untracks the generated paths and removes the copied `.rulesync/`; a destination that already exists with other text stops it with one line naming both paths, and `repo sync --check` reports the pending steps. `rulesync` is now a dependency of `@workerstack/repo`, since the install-time sync runs it. `repo generate`, `repo upgrade`, the `repo:rulesync:*` package scripts and the feature-packs file are gone: upgrade by bumping the dependency and running `bun install`, and regenerate with `bun repo sync`.
+- **Breaking:** every script, hook and the CLI is TypeScript run by bun. `.rulesync/scripts/*.mjs` became `.rulesync/scripts/*.ts`, the grok hooks became `.grok/hooks/*.ts`, and the bin is `bin/repo.ts`. Generated hook commands read `bun "$d/…ts"`, and `.githooks/commit-msg` runs under `bun`. The old `.mjs` paths are gone; run commands as `bun repo <cmd>`. A consumer's own hook script keeps whatever extension bun runs. `repo doctor` gains a `bun` version row and finds node only on your PATH.
+- The stock references moved from `.rulesync/reference/` to `references/` and ship in the package. Agents read them from `node_modules/@workerstack/repo/references/`, so `AGENTS.md` and the skills point there, and `repo init` no longer copies them. `law.md`, `skills-map.md` and `refs-map.md` are gone: `references/INDEX.md` holds the catalogs in its `repo:skills`, `repo:refs`, `repo:packages` and `repo:stack` sections. The first `repo sync` in a repo an older init copied removes the unchanged stock copies in `.rulesync/reference/` and moves each file or section of yours to `references/`.
+- The `repo` bin runs on bun.
+- Scripts and hooks run through the `repo` bin. Agents and people run `bun repo <cmd>` (`job`, `worktree`, `lessons`, `browser`, `google-workspace`, `jev`, `listen`, `speak`, `setup`, `doctor`, `clean`, `sync-globals`, `purge-mcps`, `tasks`, `map`), and every generated hook runs `"$d/node_modules/.bin/repo" hook <name>`, which prints `run bun install` and exits 1 in a checkout with no install. The gate rewrites fat calls to `<root>/node_modules/.bin/repo job …`, and `repo sync --check` fails a repo hook still in the script form. A consumer has no `.rulesync/scripts/` copy, so a direct `bun .rulesync/scripts/<name>.ts` call fails there; use `bun repo <cmd>`. Never type `bunx repo`, which fetches an unrelated npm package.
+- The gate now covers Antigravity 1.5.3's `write_file` and `edit_file` and reads its `lastUserInput` for a named git subcommand (a subagent gets no grant); generated agents name models their CLIs accept (`gpt-6-luna`, `grok-4.7`, the Antigravity tiers `flash_lite`, `flash` and `pro`; Cursor agents inherit the parent session's model) with Antigravity's real tool names, and `repo doctor` gains an `agent models` row that flags a model a CLI no longer offers.
+- Agents never change product files in the main checkout: the gate denies a write, a commit, destructive git and a lesson save there, and a force push, a delete of the default branch or another session's `wt/*`, unless the user's message names the git command. Work starts with `worktree.mjs add <name>`, and the new `worktree.mjs finish [<name>]` rebases the branch onto the default branch, fast-forwards it and removes the worktree, without pushing. `repo doctor` lists a `stale worktree` unmerged for 7 days
+
+### Fixed
+
+- `repo turn` and the pre-commit hook no longer fail lint when every staged file is one oxlint ignores; oxlint's note before its report was read as a failure.
+- The generated CI passes on Linux, macOS and Windows. On Windows, `repo sync` marks `.githooks/*` executable in the git index, the red-proof and release `tar` calls no longer pass a `C:` path that GNU tar reads as a remote host, `repo browser` kills the whole engine process tree and reports an engine that cannot start instead of crashing, and `rtk` is started through a cross-platform spawn. `repo ci --no-coverage` runs the gates without coverage floors, and the generated `ci.yml` uses it on macOS and Windows, so the floors are enforced on Linux only.
+- Hooks run from the main checkout's install when a worktree has none, for every host.
+- Antigravity loads the generated agents again (agy rejected their `gemini-3.8-flash-*` models and dropped every agent), and the Antigravity orchestrator can run commands, edit files and invoke subagents.

package/LICENSE

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

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/agents/global-settings/antigravity.json

@@ -0,0 +1,3 @@
+{
+  "toolPermission": "always-proceed"
+}

package/agents/global-settings/claude.json

@@ -0,0 +1,6 @@
+{
+  "permissions": {
+    "defaultMode": "bypassPermissions"
+  },
+  "skipDangerousModePermissionPrompt": true
+}

package/agents/global-settings/codex.toml

@@ -0,0 +1,2 @@
+approval_policy = "never"
+sandbox_mode = "danger-full-access"

package/agents/global-settings/cursor.json

@@ -0,0 +1,3 @@
+{
+  "approvalMode": "unrestricted"
+}

package/agents/global-settings/grok.toml

@@ -0,0 +1,36 @@
+# NOT auto-loaded by Grok. Merged into ~/.grok/config.toml by:
+#   bun repo yolo --dry-run  # preview
+#   bun repo yolo            # write machine-wide (~/.grok; all Grok sessions on this host)
+# Project .grok/config.toml only loads MCP, plugins, and permission rules.
+#
+# [features] two_pass_compaction is not live until copied to ~/.grok/config.toml.
+# Project .grok/config.toml cannot set [features]. Do not add a SessionStart hook.
+# grok models (2026-11-07): grok-4.7 only.
+# Orchestrator effort: agent frontmatter has no reasoning_effort key (unknown fields ignored).
+# Use `/effort low` or set reasoning_effort in ~/.grok/config.toml. Do not put effort strings in tools:.
+
+[ui]
+permission_mode = "always-approve"
+
+[agent]
+name = "orchestrator"
+# SSOT: .grok/agents/orchestrator.md (discovered).
+
+[subagents.toggle]
+explore = true
+plan = true
+general-purpose = true
+
+[subagents.models]
+explore = "grok-4.7"
+scout = "grok-4.7"
+
+[compat.claude]
+agents = false
+
+[memory]
+enabled = false
+
+# Must be copied to ~/.grok/config.toml. Project .grok/config.toml cannot set [features].
+[features]
+two_pass_compaction = true

package/agents/global-settings/manifest.json

@@ -0,0 +1,36 @@
+{
+  "version": 1,
+  "skipKeyPattern": "^(secrets?|api[_-]?key|access[_-]?token|tokens?|passwords?|authorization|mcp(servers)?|hooks)$",
+  "hosts": [
+    {
+      "id": "grok",
+      "format": "toml",
+      "payload": "agents/global-settings/grok.toml",
+      "dest": ".grok/config.toml"
+    },
+    {
+      "id": "claude",
+      "format": "json",
+      "payload": "agents/global-settings/claude.json",
+      "dest": ".claude/settings.json"
+    },
+    {
+      "id": "codex",
+      "format": "toml",
+      "payload": "agents/global-settings/codex.toml",
+      "dest": ".codex/config.toml"
+    },
+    {
+      "id": "antigravity",
+      "format": "json",
+      "payload": "agents/global-settings/antigravity.json",
+      "dest": ".gemini/antigravity-cli/settings.json"
+    },
+    {
+      "id": "cursor",
+      "format": "json",
+      "payload": "agents/global-settings/cursor.json",
+      "dest": ".cursor/cli-config.json"
+    }
+  ]
+}

package/agents/grok/hooks/orchestrate-parent.json

@@ -0,0 +1,60 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "repo hook orchestrate-parent",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "spawn_subagent|Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "repo hook orchestrate-parent",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "repo hook orchestrate-parent",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "repo hook orchestrate-parent",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "repo hook orchestrate-parent",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/agents/grok/hooks/rtk.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "repo hook rtk-grok",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/agents/grok/hooks/rulesync.json

@@ -0,0 +1,3 @@
+{
+  "hooks": {}
+}

package/agents/grok/roles/scout.toml

@@ -0,0 +1,5 @@
+description = "Low reasoning role"
+default_capability_mode = "all"
+reasoning_effort = "low"
+model = "grok-4.7"
+default_fork_context = false

package/agents/hooks.jsonc

@@ -0,0 +1,67 @@
+{
+  "version": 1,
+  "hooks": {
+    // Claude / Codex / Antigravity / Cursor only (generate -t omits grokcli for hooks).
+    // Cursor takes these matchers untranslated, so they name its tools too (Shell, Read, Write, Grep).
+    // Grok spawn/fat SSOT is hand-placed cli/scripts/orchestrate-parent.ts + orchestrate-parent.json.
+    // A repo hook command is written `repo hook <name>`; sync expands it through hookCommand(). `repo sync --check` fails any other form.
+    "preToolUse": [
+      {
+        "matcher": "spawn_subagent|Task|Agent|spawn_agent",
+        "type": "command",
+        "command": "repo hook scrub-spawn-prompt",
+        "timeout": 5
+      },
+      {
+        // Fat Read/Grep/Glob/Bash + Write/Edit scratch rewrite. Writes are denied only to an implementer-* child (plan, journal) and to the parent while a review-* plan runs (outside .tmp/).
+        "matcher": "Read|read_file|Grep|grep|Glob|list_dir|Bash|Shell|run_terminal_command|Write|Edit|write|search_replace|apply_patch|write_file|edit_file|run_command",
+        "type": "command",
+        "command": "repo hook gate-fat-tools",
+        "timeout": 5
+      },
+      {
+        // Persist rewrite + fat-gate for session writes/reads. Grok json stays no-matcher (Read included).
+        "matcher": "Write|Edit|write|search_replace|Bash|Shell|run_terminal_command|Skill|skill|run_command|Read|read_file|Grep|grep|Glob|list_dir",
+        "type": "command",
+        "command": "repo hook orchestrate-parent",
+        "timeout": 5
+      }
+    ],
+    "sessionStart": [
+      {
+        // Code-only folder map as additionalContext (hooks-union keeps it first).
+        "type": "command",
+        "command": "repo hook session-map",
+        "timeout": 5
+      }
+    ],
+    "beforeSubmitPrompt": [
+      {
+        "type": "command",
+        "command": "repo hook orchestrate-parent",
+        "timeout": 5
+      }
+    ],
+    "stop": [
+      {
+        "type": "command",
+        "command": "repo hook orchestrate-parent",
+        "timeout": 30
+      }
+    ],
+    "subagentStop": [
+      {
+        "type": "command",
+        "command": "repo hook orchestrate-parent",
+        "timeout": 30
+      }
+    ]
+  },
+  "claudecode": {
+    // Claude Code only: claude -w, EnterWorktree and worktree subagents land in .worktrees/<name> on wt/<name>.
+    "hooks": {
+      "worktreeCreate": [{ "type": "command", "command": "repo hook worktree", "timeout": 60 }],
+      "worktreeRemove": [{ "type": "command", "command": "repo hook worktree", "timeout": 60 }]
+    }
+  }
+}

package/agents/mcp-policy.jsonc

@@ -0,0 +1,16 @@
+// MCP deny-default SSOT. Named allow is empty this pass; do not add cloudflare/docker.
+{
+  "default": "deny",
+  "allow": [],
+  "plugins": {
+    "denyDefault": true
+  },
+  "servers": {},
+  "agents": {
+    "orchestrator": { "inherit": false },
+    "scout": { "inherit": false },
+    "researcher": { "inherit": false },
+    "implementer-fast": { "inherit": false },
+    "implementer-deep": { "inherit": false }
+  }
+}

package/agents/rules/overview.md

@@ -0,0 +1,21 @@
+---
+description: Reply style, working rules and where plans live
+---
+en-US default. Talk like a partner on the user's side who needs this to ship as much as they do: their goal is yours, and a miss is yours too. Plain, whole sentences, only what the person needs to act. Length follows the stakes. When something is broken or urgent, give the problem and the next step in one or two sentences, then stop. One sentence is enough when that is the whole answer. No background they did not ask for, no explaining what they already know, no cold Wikipedia-style fact dump, no arrows, `key=value` tokens, verbless fragments, or internal names they did not use. A question or a work result is glanceable. Open with where we stand against their goal: what landed, what is stuck, risky, or unverified, with paths, counts, and pass or fail. When they must act, say what you need from them, grouped by where they do it, each step exact enough to do without asking back, then what you will do once they have. "We" for the goal, "you" for their steps, "I" for yours. The middle is only new why or risk. The last line is the one action or decision, and it must add information. Do not restate the open. Care shows as precision and follow-through: bad news first and plain, with what you are doing about it. No praise, reassurance or hedging, and a mixed result stays mixed. Output another agent reads (subagent returns, job stdout, spawn prompts) and files you write (plans, handoffs, roadmaps, commits, PRs, docs, code comments) keep their own format, as does a slash skill that defines its reply or a raw artifact to copy.
+
+Examples are a class. `...`, `etc` / etcetera, and a `;` between specimens are that same class. An example, an open list, or a negative example means infer the class and do what reasonably fits this case, including what they did not name. Do not copy the example's words, stop at the named items, or add work outside the class. In a plan or a spawn prompt, pass the class. A `;` in code or an ordinary clause is not that cue. Closed instructions stay literal.
+
+Ship optimal solutions only; rewrite if not. Flag blockers. Do not monkey-patch. When advising, recommend the optimal choice based on research, data, and reasoning, not the user's preference. Be thorough in your analysis and bold in your recommendations. Change it only for new evidence or a flaw found in it. Pushback or a leading question is not a reason to switch; keep the recommendation and explain why. Do and verify the work yourself with every tool and credential you have. Don't guess, say "likely" or similar, trust older memory, stop short, leave placeholders, or hand the user anything you could do. Stopping for approval of a written plan is not stopping short. Ask only when you truly lack the means (the user's intent and preferences count), and say what you tried. Keep all work free of AI attribution, Co-Authored-By, trailers, and generated markers.
+
+Plan first. A straight shot is one file, one obvious edit, and nothing to decide: run it with `/do`. Anything else: the plan caps the result, so research until every leaf is defensible, ask what only the user can answer, and research again on each answer. A clear task gets one plan; an unclear one gets rounds. Then `/write-plan`, stop with `Reply "y" to run plan {n} (strategy: {s}), or …`, revise on feedback, and `/implement-plan` on `y`. `/show-me` restates the proposal as before and after. Two or more ordered slices are `/write-roadmap`. Detail: `node_modules/@workerstack/repo/references/scope.md`.
+By default (`/auto`) you keep going and ask only on blockers. Under `/ask` you finish one step, then ask. Under `/away` you decide instead of asking and log each choice in the plan.
+Inside your own worktree any git is fine: stash, reset, checkout, rebase, amend. In the main checkout and from anywhere on the default branch, run no destructive git (stash, reset, checkout, switch, restore, clean, rebase, branch -D of the default branch, force push) unless the user's message asks for it; the gate denies it otherwise. The stash is repo-wide: never drop or clear stashes you did not make.
+Never change product files in the main checkout; the gate denies writes and commits there. Every change, a straight shot or a lesson too, starts with `bun repo worktree add <name>` (it prints `.worktrees/<name>`, on `wt/<name>`); edit, test and commit there, then run `bun repo worktree finish <name>` from the root, which rebases onto the default branch, fast-forwards it and removes the worktree. Scratch, plans and journals stay in the root `.tmp/repo/`.
+
+Read `node_modules/@workerstack/repo/references/INDEX.md` once. When a row matches the work, read that reference in full.
+To learn the repo layout, use the folder map if it is in your context. If it is missing, or you need more depth, run `bun repo map [dir]` instead of exploring with `ls` or `find`.
+
+Large dumps are compressed (search, test logs, snaps). Scratch and dumps live in `.tmp/repo/` (gitignored). After a write, recap the absolute path; edit with an offset slice when you need lines.
+For a fat dump, 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.
+
+Browse with `bun repo browser`. Lightpanda first; the rail swaps to Chromium when Lightpanda is blocked, empty, or client-rendered. Do not stop and say you cannot. App e2e is `playwright test`.

package/agents/settings/claude.json

@@ -0,0 +1,5 @@
+{
+  "permissions": {
+    "deny": ["Agent(Explore)", "Agent(Plan)", "Agent(general-purpose)"]
+  }
+}

package/agents/skills/ask/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: ask
+description: 'Session flag. Finish one step, recap, then ask before the next.'
+---
+# ask
+
+Session flag. Slash `/ask` stamps this session.
+
+Finish one coherent step. Recap what landed. Ask whether to continue. Wait. Do not start the next step in this turn.
+
+`/auto` is the default: keep going; ask only on blockers. Slash `/auto` unlinks the stamp and returns this session to auto.
+
+`/away` is the third flag: decide instead of asking, and log each choice.

package/agents/skills/auto/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: auto
+description: >-
+  Session flag. Default. Work the task through. Ask on blockers instead of
+  monkey-patching.
+---
+# auto
+
+Session flag. Default. Slash `/auto` unlinks any `/ask` or `/away` stamp on this session.
+
+Work the task through. Do not stop after each step. When a blocker, missing fact, or real choice appears, stop and ask. Do not monkey-patch around a failure.
+
+`/ask` is a second flag: one step, then ask. `/away` is the third: decide instead of asking, and log each choice.

package/agents/skills/away/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: away
+description: 'Session flag. Nobody is watching: decide instead of asking, log each choice, keep going.'
+---
+# away
+
+Session flag. Slash `/away` stamps this session away.
+
+Never ask. When a question comes up, decide it, log it, and continue. Log each choice in the plan's (or roadmap's) `## Previous mistakes` as `- decision: {question} → {choice}, because {why}`. Entries are append-only and sit outside the cap.
+
+Replies are agent-terse: what landed, paths, pass or fail. Nobody reads them live.
+
+Still stop on a true blocker: a missing credential, a destructive action. The Stop hook blocks a reply that ends in a question with `away: do not ask; decide, log "- decision: {question} → {choice}, because {why}" in the plan, and continue`. After 3 blocks it lets the question through.
+
+Frontmatter `mode:` on this session's in-progress plan or roadmap wins over the flag.
+
+Approval still happens before an away run. Write and review the plan, end with the closing line, and wait for `y` or `h`.
+
+`/auto` returns this session to the default. `/ask` is the other flag: one step, then ask.

package/agents/skills/blast-radius/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: blast-radius
+description: >-
+  Find what a change could break somewhere else before it ships, beyond the
+  diff, and prove the one fact it's safe because of by running real code instead
+  of writing it up. Use for /blast-radius, 'blast radius of X', 'what could this
+  break', or reviewing a small diff you don't trust.
+---
+# Blast radius
+
+Find what a change breaks somewhere else, before it ships. Use for "blast radius of X", "what could this break", or reviewing a small diff you don't trust yet.
+
+Slash `/blast-radius` only. Not a session flag.
+
+This is not a walkthrough of what the code does, and not a history of why it was built. Blast radius is what the change breaks somewhere else.
+
+Listing the callers is not the job. The agent can grep those in a second. The job is the breakage grep won't show you.
+
+## Don't trust your own writeup
+
+A blast-radius writeup that sounds right is worthless. It reads as convincing whether or not it's true. So don't hand back the writeup. Find the one or two facts the whole thing depends on and prove them by running code.
+
+### How sure are you
+
+For each fact the change's safety depends on, get it as far down this list as is cheap, and say where it stopped.
+
+1. You said so. Worthless on its own.
+2. You pointed at the line. A real `file:line`, or the library's own source.
+3. You showed the bad case can't happen. You walked the failure step by step and it doesn't reach.
+4. You ran it. A script or test that calls the real code and fails loud if you're wrong.
+5. You reproduced it in the running app.
+
+Step 4 is usually one small script that imports the same library the app ships and calls the exact function you're worried about.
+
+## Steps
+
+1. Read the change. The diff, the symbols it adds, changes, and deletes, and what it now does differently, including the part the diff doesn't spell out. Pull the PR and commits: `git log` / `git blame` on the changed files, `gh pr view` when a PR number is in the history.
+2. Find the one fact it's safe because of. Most changes that look risky are safe because of a single fact, like "this call only drops already-dead cache entries and does nothing else". Find that fact. If it holds, most risky cases are cleared at once. Spend your time here, not on a long list of maybes.
+3. Look where grep stops. Read the source of the library you call, and check its pinned version and any local patch. Work out when things run: microtasks, unmount and teardown, Solid versus React. Follow what a symbol search misses: the JSON an API returns, a DB column, a wire format, another language reading the same bytes, a feature flag, code three hops downstream.
+4. Be honest about each risk. Give it a real chance of happening and a real cost if it does. Keep the risks you confirmed. List the ones you checked and cleared separately. Cite a real `file:line`. A search that finds nothing is still an answer. Never make up a caller or an API.
+5. Prove the one fact. Write a script or test that runs the real code, run it, and paste what happened.
+6. For a big or wide change, run a second independent pass (another model or a fresh read of the same question) and merge the answers. Different models catch different real bugs.
+
+## What to hand back
+
+- **What it does.** What changed, including the part that isn't obvious.
+- **The one fact it's safe because of.** State it, say which step you got it to, and show the proof. If you couldn't prove it, write unproven.
+- **Risks.** Each names how it breaks, the `file:line`, how likely and how bad, and how to check. Paste the proof for the ones that matter.
+- **Cleared.** What you checked and why it's fine.
+- **Before you merge.** The cheapest test or repro that catches the real bug, including the script you wrote.
+
+Write it through `/unslop`, cite real code, and strip anything private before it goes anywhere public.
+
+**Reply:** the writeup above, with the one safety fact either proven or marked unproven.

package/agents/skills/bro/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: bro
+description: 'Restate the last message in plain human language, with no jargon.'
+---
+This reply only: restate the last message in plain human language. Not a mode switch or session flag. After this reply, revert to output.md.
+
+Restate your last message. Stop using jargon and speak coherently. State it more simply and concisely, like one human talking to another.
+
+Slash `/bro` only.

package/agents/skills/browser/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: browser
+description: >-
+  Browse via bun repo browser (Lightpanda). App e2e uses
+  Playwright.
+---
+Zero-config. `bun repo browser <verb>`.
+
+Verbs: `nav <url>` · `snap` · `click <ref>` · `fill <ref> <text>` · `scroll [ref|down|up|N]` · `wait [ms]` · `hover <ref>` · `select <ref> <value>` · `shot` · `pdf` · `stop` · `doctor` · `ensure`.
+
+- **snap** = default read (markdown + numbered refs). `click`/`fill` need a prior snap.
+- Lightpanda default. The rail swaps to Chromium when `shot`/`pdf`/`trace`, win32, missing Lightpanda, probe-fail once, Chromium-first hosts (figma docs/sheets/slides mail.google earth amazon), or a blocked/empty/client-rendered snap. One swap. Do not stop and say you cannot.
+- Session/profile: `.tmp/repo/browser/`. `stop` reaps; second `stop` ok.
+- Windows: Chromium even if Lightpanda exists.
+- `doctor`/`ensure` → `bun repo doctor`. Engine hints: `bun repo setup browser`. Do not read a README unless doctor/setup is missing; then https://github.com/workerstack/repo#prerequisites (not the consumer README).
+- No env. No MCP. No raw Playwright. Spec: `node_modules/@workerstack/repo/references/browser.md`.

package/agents/skills/clasp/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: clasp
+description: >-
+  Low-level Apps Script CLI. Prefer /google-workspace for sheet, doc, meeting,
+  mail.
+---
+# clasp
+
+Custom Apps Script in-repo only. Spec: `node_modules/@workerstack/repo/references/clasp.md`.
+
+Sheets, Docs, Slides, Calendar, Gmail: `bun repo google-workspace` and `node_modules/@workerstack/repo/references/google-workspace.md`.

package/agents/skills/commit/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: commit
+description: >
+  Inspect the diff and commit with a Conventional Commits subject line. Use for
+  /commit, "commit this", "commit these changes". Never git push.
+---
+Inspect `git status` + `git diff` (staged and unstaged) before the message.
+
+Diff pass on the hunks you will stage: delete narrating comments, unused defensive guards or try/catch on trusted paths, `any` casts that only silence types, dead compatibility, and unrelated hunks. Keep a comment only when it states a constraint the code cannot encode. Keep behavior otherwise. Do not spawn a reviewer.
+
+Stage only user intent. Never blind `git add -A` / `git add .`. Split unrelated concerns into multiple commits.
+
+If a unique in-progress file exists under `.tmp/repo/implementations/`, its `## Files` is the default stage set. Still inspect `git status`.
+
+Message = Conventional Commits **subject only**: `type(scope): subject` (scope optional).
+
+Types: feat fix docs style refactor perf test build ci chore revert.
+
+Subject: imperative lowercase no trailing period.
+
+NO body. NO footer. NO `Co-Authored-By`. NO `Generated with`. NO 🤖. NO trailers. No AI attribution. Work belongs to the human.
+
+One exception: when the commit-msg hook refuses the commit for its size, add one body line saying why it is that big (`git commit -m "<subject>" -m "<why>"`), or split the commit.
+
+## Where
+
+Run `git rev-parse --show-toplevel` and `git branch --show-current` first.
+
+- Managed worktree (`<root>/.worktrees/<name>` on `wt/<name>`): commit there, then run `cd <root> && bun repo worktree finish <name>` (from the root, not inside the worktree: its shell reports exit 1 after a successful finish, so do not rerun it). It rebases onto the default branch, fast-forwards it and removes the worktree. A conflict aborts the rebase and the message names the files: resolve them in the worktree, rerun the checks, run `finish` again.
+- Main checkout: the gate denies a commit there unless the user's message names commit, and `/commit` does. Commit only changes the user made there. Your own changes belong in a worktree: run `bun repo worktree add <name>`, redo the work under `.worktrees/<name>`, and commit there. `bun repo init` and `bun repo sync` also run inside a worktree, so their output is never left in the main checkout.
+- Any other linked worktree (T3 Code, Claude Desktop): commit only. `finish` cannot land it.
+
+Never git push. Never `git push`. This skill never pushes.
+
+Protocol: `node_modules/@workerstack/repo/references/cascade.md`. Do not paste.

package/agents/skills/commit-and-push/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: commit-and-push
+description: >
+  Alias of commit-push (1-release stub). Use for /commit-and-push, "commit and
+  push", "commit this and push". Must push. Prefer /commit-push.
+---
+Thin alias → the `commit-push` skill (`commit-push/SKILL.md` beside this one). Must push. Do not load /commit.
+
+Protocol: `node_modules/@workerstack/repo/references/cascade.md`. Do not paste cascade.