@workerstack/repo 0.0.0-stage → 0.1.0

package/references/scope.md

@@ -0,0 +1,76 @@
+---
+tags: [scope]
+---
+
+# Scope
+
+Plan by default. A straight shot is the exception. The plan caps the result, so its depth scales with the work. This file is the size-gate SSOT.
+
+## Gate
+
+Straight shot: one file, one obvious edit, nothing to decide. Do it, starting with `bun repo worktree add <name>` like any other change: the main checkout takes no product writes. Also skip planning for questions, lookups, commits, a follow-up inside an approved plan, and an explicit "just do it".
+
+Plan: two or more files, two or more items in the message, two or more valid approaches, cross-cutting or hard-to-undo work, or the user asked to plan. A named goal is not a named edit.
+
+`/ask` is not this loop. `/ask` pauses after each execution step. This loop pauses on questions and on the plan. `/auto` continues after approval; it does not skip approval. `/away` decides instead of asking and logs each choice as a `decision` entry; approval still comes before an away run. Frontmatter `mode: ask|auto|away` on this session's in-progress plan or roadmap wins over the flag. `/do <task>` skips the plan and its review, never the worktree, the nearest test or the commit gate; a change that needs a decision goes to `/write-plan`.
+
+## Research
+
+Read and search until every leaf is defensible and needs no re-planning. Depth scales with stakes and ambiguity: a clear task needs enough to write the leaves; an unclear, cross-cutting, or hard-to-undo one needs the alternatives checked against the code, docs, and data. Fat notes go under `.tmp/repo/`.
+
+## Questions
+
+Ask only what research cannot settle and what changes the plan's shape: intent, scope, a trade-off the user owns. Batch them into one round, each with your recommendation. Research again on each answer, and ask again only if a new plan-shaping gap appears. When research settles everything, skip this step and write the plan in one shot.
+
+## Plan
+
+`/write-plan`. Format: `node_modules/@workerstack/repo/references/plan-format.md`. A plan over 100 lines above `## Previous mistakes`, frontmatter included, is a roadmap: split it with `/write-roadmap`. The plan is the proposal: the chosen approach and its rejected alternative sit in Context or Constraints. A minor open choice is written as the default plus "confirm"; a plan-shaping one goes back to Questions. Before writing, run `bun repo lessons match` on the files the plan touches and cite each match in Watch-outs. After saving, run `/review-plan {n}` in a fresh agent, settle each finding, add a `review` entry to `## Previous mistakes` for each one you accept, and bump frontmatter `reviews` in that save. Write `mode:` beside `strategy:` only when the session runs `/away` or the person asked for a mode. Report the goal, phases, top risks, open assumptions, path, and the strategy with its reason, then stop with the closing line `Reply "y" to run plan {n} (strategy: {s}), or "y {a}" / "y {b}", or "h" / "h fast" / "h deep" for a fresh session.` (`/write-plan` has the full form). The closing line comes only after the review settled, with `reviews` bumped since the review spawn; the Stop hook blocks it before that.
+
+## Approval
+
+Feedback revises the same plan file (a Write of a saved plan updates it in place) and adds a `feedback` entry to `## Previous mistakes`; research again if needed. Run `/review-plan` again on the revision. Stop again until the user approves. A plan with `reviews: 0` cannot move to `in-progress`; run `/review-plan {n}` first. Approval is the user replying `y` (or `y {strategy}`) to the closing `Reply "y" to run …` line, an explicit "plan and do it" in the request, or `/implement-roadmap` running a roadmap whose status is `locked` or `in-progress`. A plan-shaping question still stops and leaves that roadmap `locked` or `in-progress`. `h` hands the whole line to a fresh session and keeps each file's strategy; `h fast` and `h deep` write `review-fast` or `review-deep` first. The hook writes one handoff and names the `/pickup {serial}` to run there; do no work in this session. A `y` or `h` on an item whose review has not settled is refused.
+
+## Implement
+
+`/implement-plan` after approval. Same turn when the request said "plan and do it", or when `/implement-roadmap` is running a `locked` or `in-progress` roadmap. Skip `[x]`. Write-allowlist = paths listed in the plan, repo-relative to that worktree. Do not skip test leaves. Work in the plan's worktree `{serial}-{name}` (`worktree.ts add`). Before the first leaf, check the latest commits and read the plan's `## Previous mistakes`. A failed Verify, a test that failed after a fix, or `principle-attack-the-premise` firing adds a `verify` or `premise` entry. An entry that will happen again on other tasks also becomes a lesson, written in that worktree: `node_modules/@workerstack/repo/references/lessons.md`. Journal: `node_modules/@workerstack/repo/references/implementation-format.md` under `.tmp/repo/implementations/` (create on start; not for straight shots). Straight shot: run the nearest existing test when the repo has one, repro a bug before the edit, and scaffold a test file only for a bug. Before you call a straight shot done, read `principle-prove-it-works`. Before you ask the user, read `principle-never-block-on-the-human`. Under away, log a `decision` entry instead of asking. Before a large dump or a fan-out, read `principle-guard-the-context-window`.
+
+## Types
+
+One type per plan. Pick the strongest match. A feature that crosses an ownership, package, or API boundary is `cross-cut`. Straight shots skip this table and follow the straight-shot rule in ## Implement. Skip a named check only with a reason in Context. Approval of the plan is the select.
+
+`/write-plan` copies the row into Steps or Verify, including a Read leaf for each named principle. Each Read leaf sits in the phase it gates, not in a phase of its own. `/implement-plan` reads that skill and follows it.
+
+A slice is one child plan, not a phase. Two or more ordered slices are a roadmap (`/write-roadmap`, then `/implement-roadmap`), not one plan. `/write-roadmap` runs `/review-roadmap {n}` in a fresh agent after each save, the same way plans are reviewed, and a roadmap with `reviews: 0` cannot be locked. Format: `node_modules/@workerstack/repo/references/roadmap-format.md`.
+
+| type | checks |
+| --- | --- |
+| bug | repro; failing test before impl; read `principle-fix-root-causes`; read `principle-test-behavior-not-implementation` |
+| feature | failing test before impl; read `principle-test-behavior-not-implementation` |
+| docs | no test leaf; no browser unless the doc is a live page; Verify reads the page or runs the generator |
+| perf | Verify states the measurement and what limits it; read `principle-explain-the-number` |
+| refactor | existing suite or characterization tests; no feature leaves; read `principle-laziness-protocol`; read `principle-subtract-before-you-add`; read `principle-minimize-reader-load`; read `principle-test-behavior-not-implementation` |
+| cross-cut | Context holds architect lite (types, signatures, module map, rejected shape); a `/blast-radius` leaf; read `principle-foundational-thinking`; read `principle-type-system-discipline` |
+| chore | no test leaf unless a check already exists |
+
+## Facts
+
+`/write-plan` adds a Read leaf for each fact that is true, in the phase that fact gates. No fact, no leaf. `/implement-plan` reads that skill and follows it.
+
+| fact | read |
+| --- | --- |
+| a guard, parser, or adapter at a CLI, config, or network edge | `principle-boundary-discipline` |
+| a new internal API while old callers still exist | `principle-migrate-callers-then-delete-legacy-apis` |
+| a command or loop that must survive crash and retry | `principle-make-operations-idempotent` |
+| two actors can write the same file, branch, or key | `principle-separate-before-serializing-shared-state` |
+| stateful logic, or the same shape copied across files | `principle-model-the-domain` |
+| a sweep of similar edits | `principle-build-the-lever` |
+| a rewrite with phase boundaries | `principle-outcome-oriented-execution` |
+| a person will see the output, the error text, or the default | `principle-experience-first` |
+| the requirement does not fit without a special-case branch | `principle-redesign-from-first-principles` |
+| research left two or more live options and the choice is hard to undo | `principle-exhaust-the-design-space` |
+
+`/implement-plan` reads a principle only when the type row names it, a true fact names it, the next sentence names it, or an already-read principle cites it. Do not open the rest of the catalog.
+
+Verify of every plan reads `principle-prove-it-works`. After two fixes that share a premise fail the same gate, read `principle-attack-the-premise` before a third try. Before you ask the user, read `principle-never-block-on-the-human`. Before a large dump or a fan-out, read `principle-guard-the-context-window`.
+
+`/write-roadmap` reads `principle-sequence-verifiable-units`. `/correct` reads `principle-encode-lessons-in-structure`.

package/references/setup.md

@@ -0,0 +1,42 @@
+---
+tags: [setup]
+---
+
+# Setup
+
+Handheld machine setup for optional integrations. Any OS. Secrets stay in `~/.workerstack/` (Windows `%USERPROFILE%\.workerstack`). Not git. Env still wins over the file.
+
+```
+bun repo setup
+bun repo setup speak
+bun repo setup listen
+bun repo setup google-workspace
+bun repo setup browser
+bun repo setup jev
+```
+
+TTY: menu with ok/missing. The menu lists enabled packs and always lists browser and jev. A pack is enabled when `agents.skills` in `workerstack.config.ts` names it. `bun repo setup <pack>` when that pack is off prints how to enable it (add it to `agents.skills`, then `bun repo sync`) and exits 1. Already ok asks redo (`--redo` skips the ask). Missing bins: print the OS command (never run it), then re-check PATH. Ends with one status line per listed target. Non-TTY needs flags (keys / `--creds`). Doctor never installs bins; setup never installs bins either.
+
+| target | what it writes | flags |
+| --- | --- | --- |
+| speak | `~/.workerstack/speak.json` | `--elevenlabs-key` `--openai-key` `--provider` `--skip-verify` |
+| listen | same file (`openai` / `listen`) plus `~/.workerstack/whisper/` | `--openai-key` `--device` `--skip-download` |
+| google-workspace | Desktop OAuth JSON + tokens under `~/.workerstack/` | `--creds PATH` `--account NAME` `--project ID` |
+| browser | nothing (print Lightpanda / Chromium hints; both required except win32 Chromium-only) | |
+| jev | `~/.workerstack/jev.json` (`apiKey`, mode 0600). `TYPESAFE_API_KEY` wins when set | `--api-key` |
+
+## Full-permission defaults
+
+`bun repo init` and `bun repo yolo` merge full-permission keys into five machine-wide files, keeping every other key (skip with `--skip-globals`). Plain `claude`, `codex`, `grok`, `agy` and `cursor-agent` then start without approval prompts; there are no `repo:<agent>` launch scripts.
+
+| host | dest under `$HOME` | keys |
+| --- | --- | --- |
+| claude | `.claude/settings.json` | `permissions.defaultMode = "bypassPermissions"`, `skipDangerousModePermissionPrompt = true` |
+| codex | `.codex/config.toml` | `approval_policy = "never"`, `sandbox_mode = "danger-full-access"` |
+| grok | `.grok/config.toml` | `[ui] permission_mode = "always-approve"` plus the orchestrator, subagent, memory and `[features]` tables |
+| antigravity | `.gemini/antigravity-cli/settings.json` | `toolPermission = "always-proceed"` |
+| cursor | `.cursor/cli-config.json` | `approvalMode = "unrestricted"` |
+
+`bun repo yolo` applies by default; `--dry-run` previews, `--check` prints one line of per-host status, exits 1 on any drift, and `--host <id>` limits it to one host; an unknown id prints `unknown host: <id>` and a deleted payload prints `missing payload: <path>`. `bun repo doctor` shows one `globals` row: `ok`, or the first drift line, which names the host, dest and key and ends with the `bun repo yolo` hint. The project hooks (gate-fat-tools, scrub-spawn-prompt) still run in bypass mode.
+
+Do not invent keys. If the session is not a TTY, tell the user to run `bun repo setup` in their terminal. This spec is enough. Do not read https://github.com/workerstack/repo#readme unless this file is missing.

package/references/speak.md

@@ -0,0 +1,59 @@
+---
+tags: [speak]
+---
+
+# Speak
+
+Text-to-speech from the session. Output only. Not STT. Not a mic. Not MCP. Speech-to-text is `/listen`: `node_modules/@workerstack/repo/references/listen.md` and `bun repo listen`.
+
+```
+bun repo speak whoami
+bun repo speak voices [--provider elevenlabs|openai]
+bun repo speak say --text "hello" [--provider elevenlabs|openai] [--voice ID] [--out path] [--play]
+```
+
+`say` writes an mp3 under `.tmp/repo/speak/` (or `--out`) and prints the path. `--play` is local `afplay` (mac) or `ffplay`.
+
+## Auth
+
+Handheld (any OS): `bun repo setup speak` or `bun repo setup` → speak. Opens the key page, hides the paste, writes `~/.workerstack/speak.json`, verifies. Non-TTY: `--elevenlabs-key` / `--openai-key`.
+
+If a key is missing or rejected, the CLI prints `setup: bun repo setup speak` and exits 1. Agents should show that line, not a stack or JSON. Do not invent a key.
+
+One key is enough. Never commit it.
+
+| | env | file |
+| --- | --- | --- |
+| ElevenLabs | `ELEVENLABS_API_KEY` | `elevenlabs.apiKey` |
+| OpenAI | `OPENAI_API_KEY` | `openai.apiKey` |
+| Force provider | `SPEAK_PROVIDER` | `provider` |
+
+`~/.workerstack/speak.json` (chmod 600):
+
+```json
+{
+  "provider": "elevenlabs",
+  "elevenlabs": {
+    "apiKey": "sk_…",
+    "voiceId": "JBFqnCBsd6RMkjVDRZzb",
+    "modelId": "eleven_multilingual_v2"
+  },
+  "openai": {
+    "apiKey": "sk-…",
+    "voice": "coral",
+    "model": "gpt-4o-mini-tts"
+  }
+}
+```
+
+Env wins over the file. Default provider is `SPEAK_PROVIDER` else the first configured key (elevenlabs, then openai).
+
+## Defaults
+
+- ElevenLabs voice: George `JBFqnCBsd6RMkjVDRZzb`. Model: `eleven_multilingual_v2`.
+- OpenAI voice: `coral`. Model: `gpt-4o-mini-tts`.
+- Format: mp3.
+
+Create an ElevenLabs key at https://elevenlabs.io/app/settings/api-keys. OpenAI at https://platform.openai.com/api-keys.
+
+Doctor reports speak as optional: `ok` when a key or `~/.workerstack/speak.json` exists, else `missing (optional)`. It prints the provider name, not the secret.

package/tsconfig/base.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "preserve",
+    "moduleResolution": "bundler",
+    "types": [],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowUnreachableCode": false,
+    "allowUnusedLabels": false,
+    "useUnknownInCatchVariables": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "noErrorTruncation": true,
+    "allowImportingTsExtensions": true
+  },
+  "files": ["./reset.d.ts"]
+}

package/tsconfig/bun.d.ts

@@ -0,0 +1 @@
+/// <reference types="bun" />

package/tsconfig/bun.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["ESNext"]
+  },
+  "files": ["./reset.d.ts", "./bun.d.ts"]
+}

package/tsconfig/reset.d.ts

@@ -0,0 +1 @@
+/// <reference types="@total-typescript/ts-reset" />

package/tsconfig/strict.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "isolatedDeclarations": true,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "declaration": true,
+    "allowJs": false
+  }
+}

package/tsconfig/web.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["DOM", "DOM.Iterable", "ESNext"]
+  }
+}

package/tsconfig/worker.d.ts

@@ -0,0 +1 @@
+/// <reference types="@cloudflare/workers-types" />

package/tsconfig/worker.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "lib": ["ESNext"]
+  },
+  "files": ["./reset.d.ts", "./worker.d.ts"]
+}