@workerstack/repo 0.0.0-stage → 0.1.0

package/agents/skills/tmp/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: tmp
+description: Dump a one-off convo artifact under .tmp/repo/.
+---
+# tmp
+
+One turn. Author from this session (email/script/note). Write once. Recap the absolute path. Stop.
+
+## Invocation
+
+`/tmp [what]`
+
+Empty `$ARGUMENTS` + no already-visible dumpable blob → `need task`. Empty + visible blob (code fence / draft) → dump that.
+
+## When
+
+Dump a one-off convo artifact. Not `/handoff` (no pickup no Goal/State/Next). Not `.tmp/repo/plans/`. Not `.tmp/repo/implementations/`. Not product source. Not OS `/tmp`.
+
+## Path
+
+`.tmp/repo/{serial}-{slug}-{YYYYMMDDTHHMMSSZ}.{ext}`
+
+- serial: unpadded int ≥ 1, next after existing tmp dumps (own counter; not plan/handoff/implementation serials)
+- slug: lower, non `[a-z0-9]` → `-`, collapse, trim 50
+- stamp: UTC `YYYYMMDDTHHMMSSZ`
+- ext: `TMP_EXT` or explicit `.{ext}` in args; else `md`
+
+## Write
+
+```
+TMP_NAME: <3-6 word name>
+TMP_EXT: md
+<artifact only>
+```
+
+`TMP_EXT` optional. Write any root filename under `.tmp/repo/` (not `plans|roadmaps|handoffs|implementations|browser|orchestrator-logs|stash|sessions`). Grok `orchestrate-parent.ts` runs `cli/scripts/persist-tmp.ts`: serial/slug/ext from `TMP_*`, strips those lines, no YAML frontmatter, rewrites path + content. Write outside that root or missing `TMP_NAME:` is denied.
+
+Host without that hook: name the file per **Path** yourself, or pipe the body to `bun repo persist tmp --workspace {repo}` and use its `absPath`.
+
+Never rewrite an existing dump; new serial. Artifact file content after hook = artifact only (no TMP_* lines no YAML frontmatter).
+
+## Report
+
+```
+[tmp]: serial={int} path={abs}/.tmp/repo/{serial}-{slug}-{stamp}.{ext}
+```
+
+Do not dump the body.
+
+## Rules
+
+- One write. `/tmp` is not a mode.
+- Secrets/tokens: refuse dump. Text artifacts only; no binary.
+- Protocol: `node_modules/@workerstack/repo/references/cascade.md`. Do not paste it here.

package/agents/skills/typescript-best-practices/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: typescript-best-practices
+description: >-
+  TypeScript best practices. Use when reading or editing any .ts or .tsx file,
+  or for /typescript-best-practices.
+---
+# TypeScript best practices
+
+Make illegal states unrepresentable. Brand semantic primitives. Parse external data at boundaries. Exhaust variants. Derive types from the schema that owns the shape.
+
+Validate at the boundary (CLI, config, network, external APIs). Trust types inside. Keep business logic in pure functions.
+
+| Rule | Summary |
+|------|---------|
+| Discriminated unions | Model variants with a `kind` literal discriminant so impossible states can't be represented. No optional-field bags. |
+| Branded types | Brand primitives with `& { readonly __brand: "X" }` so they can't be mixed up. Validate once at the boundary. A brand comes from a verifying type guard (`input is AgentId`), never from `as`. |
+| Constructive modeling | Build the shape so the illegal value can't be constructed. `[T, ...T[]]` for non-empty, `[T, T][]` for even length, `start` plus `duration` for a range. Not a runtime guard, not a wish for refinement types. |
+| Simplest total type | Keep `T[]` while every operation on it stays total. Strengthen to `NonEmpty<T>` only where the loose type forces `!`, a cast, or a "should never happen" throw. |
+| `unknown` over `any` | External data is `unknown`. |
+| Schemas before guards | Before hand-writing a property-by-property type guard, use the repository's runtime schema library and infer the type from the schema, such as `z.infer`. |
+| No `as` casts | Every `as` is a runtime crash waiting. Cast only after validation. |
+| Narrowing hierarchy | Discriminant switch > `in` operator > `typeof`/`instanceof` > user-defined type guard > `as`. |
+| Type guards | Must verify the claim. A lying guard is worse than `as` because the bug hides behind a name that says it's safe. Name them `isX` or `hasX`. |
+| Exhaustiveness | Inline `const _exhaustive: never = x;` in default arms so the compiler errors when a new variant is added. |
+| `satisfies` over `as` | Validates the value without widening literal types. |
+| Boundary validation | Parse where data crosses in, into a named domain type. `Record<string, unknown>` (however spelled) stops at that parse. Trust types inside. |
+| Schema-derived types | Reach for `Pick`/`Omit`/`Parameters`/`ReturnType`/`Awaited`/`typeof` before declaring a new interface. |
+| Object args | Pass objects, not positional, so argument order is self-documenting. Skip on hot paths (per-frame render, tokenizers, parsers). |
+| Real tests | Don't mock what you can run. Prefer the framework's real test primitives with leak/disposable checks, and verify UI in a running build. Mock only what you can't run locally. |
+| Structured telemetry | Prefer structured logger diagnostics with enough context to debug from an id. No `console.log` in shipped code. |
+
+Examples: `references/patterns.md` next to this skill.

package/agents/skills/typescript-best-practices/references/patterns.md

@@ -0,0 +1,328 @@
+# TypeScript patterns
+
+Code examples for each rule in `SKILL.md`. The underlying principles are language-agnostic.
+
+## Branded types
+
+Brand primitives so they can't be mixed up. Validate once at the boundary. Downstream code trusts the type.
+
+```ts
+type AgentId = string & { readonly __brand: "AgentId" };
+
+function isAgentId(input: string): input is AgentId {
+  return isUUID(input);
+}
+
+function parseAgentId(input: string): AgentId {
+  if (!isAgentId(input)) throw new Error(`Invalid agent id: ${input}`);
+  return input;
+}
+
+function focusAgent(id: AgentId): void {
+  /* input is trusted */
+}
+```
+
+Match the `readonly __brand: 'X'` shape. Don't invent a new convention.
+
+## Discriminated unions
+
+Model variants with a literal discriminant. Every variant shares the field name and each variant's value is unique, so impossible combos can't be represented.
+
+```ts
+// Don't. Boolean + optionals lets contradictory states exist.
+type DiffState = { loading: boolean; diff?: GitDiff; error?: string };
+
+// Do. Only valid states exist.
+type DiffState =
+  | { kind: "loading" }
+  | { kind: "ready"; diff: GitDiff }
+  | { kind: "error"; error: string };
+```
+
+Pick one discriminant name (`kind`, `type`, `tag`) and stick to it.
+
+## Constructive modeling
+
+Build the type from parts that are all legal instead of restricting a loose type with runtime checks.
+
+Non-empty, via a variadic tuple:
+
+```ts
+type NonEmpty<T> = [T, ...T[]];
+
+// Don't: T[] plus a length check every caller must repeat
+function pickWinner(entries: string[]): string {
+  if (entries.length === 0) throw new Error("no entries");
+  return entries[Math.floor(Math.random() * entries.length)];
+}
+
+// Do: an empty value of the type can't exist
+function pickWinner(entries: NonEmpty<string>): string {
+  return entries[Math.floor(Math.random() * entries.length)];
+}
+```
+
+Where a plain `T[]` arrives, narrow once with a guard. The fact then travels in the type:
+
+```ts
+const isNonEmpty = <T>(arr: T[]): arr is NonEmpty<T> => arr.length > 0;
+```
+
+Even length, as pairs:
+
+```ts
+type Pairs<T> = [T, T][];
+```
+
+A time range, as start plus duration:
+
+```ts
+// Don't: a comment holds the invariant
+type TimeRange = { start: Date; end: Date }; // start <= end
+
+// Do: a negative range can't be written; derive end when needed
+type TimeRange = { start: Date; durationMs: number };
+```
+
+Keep `durationMs` a plain number. Brand it (per Branded types) only if a raw number could be passed where a duration is expected, not by reflex. Pick the representation that makes the bad state unconstructable, then expose the reading you need on top (`pairs.flat()`, a `rangeEnd()` helper).
+
+## Simplest total type
+
+Don't strengthen everything. Keep `T[]` when every operation on it is total:
+
+```ts
+const sum = (xs: number[]) => xs.reduce((a, b) => a + b, 0); // [] is 0, fine
+```
+
+Strengthen when the loose type forces a lie at a use site. The tells are `!`, `arr[0] as T`, and a "should never happen" throw:
+
+```ts
+// Don't: partiality smuggled past the compiler
+function newestSession(sessions: Session[]): Session {
+  return sessions.at(0)!;
+}
+
+// Do: strengthen the input; the assertion disappears
+function newestSession(sessions: NonEmpty<Session>): Session {
+  return sessions[0];
+}
+```
+
+Weakening the result to `Session | undefined` is the other total signature.
+
+## `unknown` over `any`
+
+External data is always `unknown`. Narrow before use.
+
+```ts
+// Don't
+function handle(input: any) {
+  return input.foo.bar;
+}
+
+// Do
+function handle(input: unknown) {
+  if (typeof input === "object" && input !== null && "foo" in input) {
+    // narrowed; compiler verifies access
+  }
+}
+```
+
+External sources include RPC payloads, `JSON.parse`, `postMessage`, IPC, file contents, environment variables, database results.
+
+## Schemas before hand-rolled guards
+
+Before writing a property-by-property type guard for external data, look for the repository's runtime schema library and existing schemas. Let one schema own validation and derive the TypeScript type from it. Do not maintain a schema, a duplicate interface, and a guard that can drift apart.
+
+```ts
+import { z } from "zod";
+
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  role: z.enum(["admin", "member"]),
+});
+
+type User = z.infer<typeof UserSchema>;
+
+function parseUser(input: unknown): User {
+  return UserSchema.parse(input);
+}
+```
+
+Use `safeParse` when failure is an expected branch. Use the equivalent inference helper when the repository uses another schema library. Do not add a new schema dependency for one guard. This rule prefers the schema system the codebase already trusts.
+
+## No `as` casts
+
+Every `as` is a potential runtime crash. Cast only after the type system has verified the claim.
+
+```ts
+import { z } from "zod";
+
+// Don't
+const user = data as User;
+
+// Don't
+function isUser(data: unknown): data is User {
+  return typeof data === "object" && data !== null && "id" in data;
+}
+
+// Do
+const userSchema = z.object({ id: z.string(), name: z.string() });
+type User = z.infer<typeof userSchema>;
+
+function parseUser(data: unknown): User {
+  return userSchema.parse(data);
+}
+```
+
+When the type comes first, annotate the validator with the type it proves. The compiler then rejects a validator that proves less than the type. Remove `name` from the object below and the assignment fails to compile.
+
+```ts
+type User = { id: string; name: string };
+
+const userSchema: z.ZodType<User> = z.object({ id: z.string(), name: z.string() });
+```
+
+When refactoring an `as` out of existing code, identify why TypeScript can't infer:
+
+- Missing discriminant: add one, switch to a discriminated union.
+- Overly wide source type (e.g. `Record<string, unknown>`): narrow it.
+- Untyped boundary: parse with the schema that owns the shape. Add a schema only where none exists.
+- Genuinely inexpressible: use a branded type or `satisfies`.
+
+## Narrowing hierarchy
+
+From best to last-resort:
+
+1. **Discriminated union switch / if.** Compiler narrows automatically.
+2. **`in` operator.** `"key" in obj` narrows to variants containing that key.
+3. **`typeof` / `instanceof`.** For primitives and class instances.
+4. **User-defined type guard.** When the above aren't enough.
+5. **`as` cast.** Only after validation.
+
+```ts
+function area(s: Shape): number {
+  if ("radius" in s) return Math.PI * s.radius ** 2; // narrowed to circle
+  return s.width * s.height; // narrowed to rect
+}
+```
+
+## Type guards
+
+A guard must actually verify the claim. A lying guard is worse than `as`.
+
+```ts
+function isCircle(s: Shape): s is Shape & { kind: "circle" } {
+  return s.kind === "circle";
+}
+```
+
+Prefer discriminant narrowing when possible.
+
+## Exhaustiveness
+
+In default arms, assign the discriminant to a `never`-typed local.
+
+```ts
+// Value-returning switch
+function area(s: Shape): number {
+  switch (s.kind) {
+    case "circle":
+      return Math.PI * s.radius ** 2;
+    case "rect":
+      return s.width * s.height;
+    default: {
+      const _exhaustive: never = s;
+      return _exhaustive;
+    }
+  }
+}
+
+// Void switch
+function handle(s: Shape): void {
+  switch (s.kind) {
+    case "circle":
+      drawCircle(s);
+      break;
+    case "rect":
+      drawRect(s);
+      break;
+    default: {
+      const _exhaustive: never = s;
+      void _exhaustive;
+    }
+  }
+}
+```
+
+Return-style in value-returning switches, void-style in statement switches.
+
+## `satisfies` over `as`
+
+`satisfies` validates without widening literal types.
+
+```ts
+// Don't. Widens, loses literal types.
+const config = { theme: "dark", cols: 3 } as Config;
+
+// Do. Validates AND preserves literal types.
+const config = { theme: "dark", cols: 3 } satisfies Config;
+// config.theme is "dark" (literal), not string
+```
+
+## Boundary validation
+
+Validate once where data crosses in. Trust types inside.
+
+- **Wire formats** (proto, JSON-RPC): parse with `ignoreUnknownFields` so forward-compatible changes don't break old clients.
+- **Persisted JSON:** versioned blob with a try/catch around the parse.
+- **Don't re-validate** deep in call chains.
+
+## Schema-derived types
+
+When a `.proto`, OpenAPI spec, GraphQL schema, or database migration already defines a shape, derive from the generated types instead of duplicating them.
+
+```ts
+// Don't. Duplicate shape, drifts when the schema changes.
+type CheckSummary = {
+  totalCount: number;
+  checks: { name: string; status: string }[];
+};
+function renderChecks(s: CheckSummary) {
+  /* ... */
+}
+
+// Do. Derive from the generated schema type.
+import type { ChecksMessage } from "<generated module>";
+function renderChecks(s: Pick<ChecksMessage, "totalCount" | "checks">) {
+  /* ... */
+}
+```
+
+Reach for `Pick`, `Omit`, `Parameters`, `ReturnType`, `Awaited`, `typeof` before writing a new interface.
+
+## Object args
+
+```ts
+// Don't. Swap two args, still compiles.
+openFile(uri, {
+  startLineNumber: 10,
+  startColumn: 1,
+  endLineNumber: 10,
+  endColumn: 1,
+});
+
+// Do. Order-independent, self-documenting.
+openFile({
+  uri,
+  selection: {
+    startLineNumber: 10,
+    startColumn: 1,
+    endLineNumber: 10,
+    endColumn: 1,
+  },
+});
+```
+
+Skip on hot paths: per-frame render, tokenizers, parsers, anything in a tight loop where the allocation cost matters.

package/agents/skills/unslop/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: unslop
+description: Cut AI tells from any writing. Use for /unslop.
+---
+# Unslop
+
+Edit text to remove AI patterns. Scan for the patterns below, then rewrite. Preserve meaning and match the intended tone.
+
+Slash `/unslop` only. Not a session flag.
+
+## Patterns to detect and fix
+
+Rule numbers are stable ids that other skills cite. A removed rule leaves a gap.
+
+### Content
+
+3. **Superficial -ing phrases.** "highlighting...", "ensuring...", "reflecting...", "showcasing...", "fostering...". Delete or expand with real sources.
+5. **Vague attributions.** "Experts believe", "Industry reports suggest", "Some critics argue". Name the source or delete.
+
+### Language
+
+7. **AI vocabulary.** Additionally, crucial, delve, enduring, enhance, fostering, garner, interplay, intricate, landscape (abstract), pivotal, showcase, tapestry (abstract), testament, underscore, vibrant. Replace with plain words.
+8. **Fancy ways to say "is".** "serves as", "stands as", "boasts", "features". Say "is" or "has".
+9. **"Not just X, but Y."** State the point directly instead.
+10. **Rule of three.** Don't force ideas into groups of three. Use the natural number.
+11. **Synonym cycling.** Protagonist, main character, central figure, hero all in one paragraph. Pick one, repeat it.
+12. **False ranges.** "from X to Y" where X and Y aren't on a meaningful scale. List topics directly.
+
+### Style
+
+13. **Em dash overuse.** Avoid em dashes entirely. Use periods or commas only (no parentheses, no en dashes, no hyphen-as-dash substitutes). If a thought needs separation, end the sentence or use a comma.
+14. **Colon overuse.** Colons are fine before a list or example, not as mid-sentence connectors. "If you're coming from traditional automation: instead of registering event handlers, you describe conditions" adds nothing with the colon. Rewrite to let the point stand on its own without comparison framing. "Describing when the scheduler should fire works best as plain English." Same meaning, no crutch punctuation.
+15. **Boldface overuse.** Don't bold every proper noun or acronym.
+16. **Inline-header lists.** The tell is a bold label and colon that restates the line: "**Performance:** Performance improved...". Convert those to prose. A bold lead-in that ends in a period, names the item, and is followed by genuinely new detail ("**Schema in TypeScript.** Tables live in one file.") is fine, not a tell.
+17. **Title case headings.** Use sentence case.
+18. **Decorative emojis.** Remove from headings and bullets.
+19. **Curly quotes.** Use straight quotes.
+
+### Communication artifacts
+
+20. **Chatbot phrases.** "I hope this helps!", "Let me know if...", "Of course!", "Certainly!", "Found the smoking gun!" Remove.
+22. **Sycophantic tone.** "Great question! You're absolutely right!" Respond directly.
+
+### Filler
+
+23. **Filler phrases.** "In order to" becomes "To". "Due to the fact that" becomes "Because". Delete "It is important to note that".
+24. **Excessive hedging.** "could potentially possibly be argued that it might" becomes "may".
+25. **Generic conclusions.** "The future looks bright." State specific plans or facts.
+
+### Jargon
+
+26. **Abstract metaphor nouns.** Substrate (base), wedge, wedge in (add), vector (way, method), locus, vantage, nexus, primitive as a noun, harness as a metaphor, surface as in "API surface", bedrock, scaffolding as a metaphor, modality, paradigm, gold-plating (more than the job needs), ratchet as a metaphor (the mechanism's real name, or a limit that only tightens), evacuate for moving code (move out), endgame (the last phase), north star, flywheel. These read as technical but usually have a plainer concrete word. Pick the concrete word.
+
+### Plain speech
+
+27. **Say what it does, not how it feels.** "the database stays close at hand", "SQL you can read", "types that follow your schema" name a feeling. The fix names the mechanism or a number: "`.toSQL()` returns the exact string sent to the database", "a column rename fails the build". Ask what the sentence tells the reader to do or know, then write that. If you can't restate it as a concrete instruction, fact, or number, cut it. One more check: if the sentence could appear unchanged in another project's docs, it says nothing about this one. Cut it.
+28. **Shorten or split dense sentences.** If the reader has to backtrack to parse a sentence, break it in two or drop clauses. One idea per sentence.
+29. **Active voice.** Prefer it. Catch "is/are/was/were + past participle" and name the actor: "queries are validated" becomes "the compiler validates queries", "the file is parsed by the loader" becomes "the loader parses the file". Passive is fine only when the actor is unknown or genuinely doesn't matter.
+30. **Cut adverbs, or use a stronger verb.** "runs quickly" becomes "is fast" or the number, and "significantly improves" becomes the measured delta. An adverb propping up a weak verb means the verb is wrong.
+31. **Prefer the plain word.** "utilize" and "leverage" become "use", "facilitate" becomes "help", "numerous" becomes "many", "in the event that" becomes "if". The fancier synonym is rarely clearer.
+32. **Mannered prose.** Metaphor or flourish where a literal phrase exists: aphorisms ("wire it or delete it"), rhetorical fragments for effect, personified code ("the plan holds it"), figurative verbs ("rides along", "stands on"), stock framing phrases. "A dial worth turning" becomes "a parameter worth varying". Say what you mean. Rule 26 covers the metaphor nouns.
+33. **Over-compression.** Dropped articles, verbless fragments, symbol-speak, and abbreviations that make the reader decode instead of read. "Parser rejects bad date → exit 2, no write" becomes "The parser rejects a bad date, exits with code 2, and writes nothing." Write whole sentences with their articles and verbs, and spell out arrows and abbreviations.

package/agents/skills/write-plan/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: write-plan
+description: 'Write a local checklist under .tmp/repo/plans/. Then /implement-plan {n}.'
+---
+# write-plan
+
+You author the plan. Persist under `.tmp/repo/plans/` via Write (hook runs `cli/scripts/persist-plan.ts`). Format: `node_modules/@workerstack/repo/references/plan-format.md`.
+
+Empty task → ask for a task and stop.
+
+Body's first line is `PLAN_NAME: <3-6 word name>`, then the `commit:` and `strategy:` lines, `# {slug}`, and the 5-line card (`WHAT`, `WHY`, `RISK`, `TOUCH`, `DONE`, padded to 7 columns, each line ≤120 characters) that sums up Goal and Steps for a glance. Then Goal, Usage, Context, Constraints, Watch-outs, Steps, Verify, and `## Previous mistakes` with `(none)`. Usage shows what a person or agent types and sees once the plan lands: every new or changed command, flag, output, error message, or file, in fenced blocks, with the before for each changed one; a plan with no visible change writes `No visible change:` and why. All boxes `[ ]`. Tests: new behavior or bug → failing test leaf before impl; other behavior → test leaf right after impl; docs/rename/config/generated → skip. Verify is the end gate.
+
+After research, pick one type from `node_modules/@workerstack/repo/references/scope.md` ## Types. Context starts with `Task type: {name}` and `Named checks:`. Copy that row's checks into Steps or Verify, with a Read leaf for each named principle and for every fact in ## Facts that is true of this plan. No fact, no leaf. Each Read leaf goes first in the phase it gates, never in a phase of its own. Verify includes a Read leaf for `principle-prove-it-works`. For `cross-cut`, Context also holds architect lite: types, signatures, module map, and the rejected shape. A named check that does not apply is a Context skip with a reason.
+
+Before you ask the user, read `principle-never-block-on-the-human`. Ask only when the user alone can answer or the action is destructive. Before a large dump or a fan-out, read `principle-guard-the-context-window` and route the bulk through `bun repo job`.
+
+Leaves cite repo-relative paths (`cli/scripts/x.ts`): the plan's worktree `{serial}-{name}` does not exist yet, and `/implement-plan` applies the paths inside it. When adjacent phases write disjoint files, end each phase line with `(parallel: <path>, …)` listing every file its leaves write.
+
+Before writing, run `bun repo lessons match` on the repo-relative paths the plan names. Cite each matched lesson path in Watch-outs with what this plan does about it; the save denies a plan that leaves one out. Lessons: `node_modules/@workerstack/repo/references/lessons.md`.
+
+Author `commit: type(scope): subject` on its own line before persist (scope optional). Conventional Commits subject: imperative lowercase, no trailing period. Types: feat fix docs style refactor perf test build ci chore revert.
+
+Author `strategy: default|review-fast|review-deep` on its own line beside `commit:`. `default` for a small or docs-only plan. `review-fast` for multi-phase code work. `review-deep` for cross-cut, hook or gate, or hard-to-undo work. A roadmap slice copies the roadmap's value unless its scope argues for another. Meanings: `node_modules/@workerstack/repo/references/plan-format.md`.
+
+Author `mode: away` on its own line beside `strategy:` only when this session runs `/away`, and `mode: ask|auto|away` only when the person asked for that mode. Otherwise send no `mode:` line.
+
+The plan is the proposal and caps the result (`node_modules/@workerstack/repo/references/scope.md`). A plan over 100 lines above `## Previous mistakes`, frontmatter included, is two or more slices: write a roadmap (`/write-roadmap`) instead. Before writing, research until every leaf is defensible; ask any plan-shaping question the user alone can answer, then research again on the answer. Do not default a plan-shaping choice. A minor open choice goes under Constraints as the chosen default plus "confirm".
+
+After the save, spawn a fresh host agent whose prompt is only `/review-plan {n}` and the plan's absolute path (on Claude Code the `claude` agent type; scout is not the reviewer). Accept or reject each finding with a reason. Apply accepted ones to the same plan file and add one `- review: …` entry each to `## Previous mistakes`. One review round per write or revision. Bump frontmatter `reviews` by one in the same save that settles the round, even when it had no findings; send the full frontmatter for that save. Every Write that sends full frontmatter carries the current `reviews`: the save denies one that lowers or drops it.
+
+On feedback, revise the same file (a Write of the saved path updates it in place) and add a `- feedback: …` entry for what the user rejected and what changed. Never edit or drop an earlier entry. When the mistake will happen again on other tasks, run `bun repo lessons match` on the files involved, then `bun repo lessons hit <slug> --evidence "plan {n}"` or write a new lesson inside the plan's worktree `{serial}-{name}` (`bun repo worktree add {serial}-{name}` if it is missing), so it lands with the plan's commit, and end the entry with `(lesson: {slug})`.
+
+Report: serial N at the absolute path the Write returned (`/…/.tmp/repo/plans/{file}`, never repo-relative), the goal, the phase list, the top risks, and any assumption to confirm. Do not dump the plan. End with the closing line only after the review settled: `reviews` was bumped in the save after the review spawn. Before that the Stop hook blocks the line, and a `y` or `h` on an unsettled item is refused. Stop and end the reply with two lines: `Strategy: {s}, because …` in one sentence, then 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.` Each `{a}` and `{b}` is a strategy other than `{s}`, in the order default, review-fast, review-deep. When other reviewed plans or roadmaps from this session wait too, it stays one line: `Reply "y" to run plan {n} (strategy: {s}), then plan {m} (strategy: {s}), then roadmap {k} (strategy: {s}), or …, or "h" / "h fast" / "h deep" for a fresh session.` in run order, where each item shows the strategy in its file and the first `or` list holds every strategy that not all items hold. The Stop hook names the exact line when yours is off. Ask for approval no other way. A bare `y` approves exactly that line. `y {strategy}` approves it with that strategy, which the hook writes into each plan the line names. `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 for the line; tell the person to run the `/pickup {serial}` it names in a fresh session, and do no work here. On feedback, revise this file, run `/review-plan` again, and stop again with the closing line. Run `/implement-plan {n}` in the same turn when the request said "plan and do it", or when `/implement-roadmap` is running a `locked` or `in-progress` roadmap. A plan-shaping question still stops.

package/agents/skills/write-roadmap/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: write-roadmap
+description: >-
+  Write an ordered program of plans under .tmp/repo/roadmaps/. Use for
+  /write-roadmap. Stops for y, which locks and runs it.
+---
+# write-roadmap
+
+You author the roadmap. First read `principle-sequence-verifiable-units` and follow it. Persist under `.tmp/repo/roadmaps/` via Write (hook runs `cli/scripts/persist-roadmap.ts`). Copy the shape below. All boxes `[ ]`. Status stays `draft` until the user replies `y`.
+
+Author a bare `strategy: {value}` line above `ROADMAP_NAME:`. Values and the heuristic: `/write-plan`. Add a bare `mode: {value}` line beside it on the same terms as `/write-plan`: `away` when this session runs `/away`, or the mode the person asked for.
+
+Before you ask the user, read `principle-never-block-on-the-human`. Ask only when the user alone can answer.
+
+Two or more slices. One slice is `/write-plan`: say so and stop. Do not write a file.
+
+Research until every slice is defensible. Ask only what changes the program. Then write the draft and stop.
+
+After each save, spawn a fresh host agent whose prompt is only `/review-roadmap {n}` and the roadmap's absolute path (on Claude Code the `claude` agent type; scout is not the reviewer). Accept or reject each finding with a reason. Apply accepted ones to the same file and add one `- review: …` entry each to `## Previous mistakes`. Bump `reviews` by one in the save that settles the round, even with no findings: send a bare `reviews: {n}` line above `ROADMAP_NAME:`. The save denies a lower count.
+
+On feedback, revise the same file (a Write of the saved path updates it in place), add a `- feedback: …` entry for what the user rejected and what changed, and run `/review-roadmap` again. Never edit or drop an earlier entry.
+
+On `y`, set `status: locked` on the same file, then run `/implement-roadmap {n}`. On `h`, `h fast` or `h deep`, the hook writes the handoff: tell the person to run the `/pickup {serial}` it names in a fresh session, and do no work here. The save denies the lock while `reviews` is 0. Do not run `/write-plan` or `/implement-plan` from this skill.
+
+Report the serial, the absolute path, the slice titles in order, the top risk, and the review findings you rejected with why. Stop and end the reply with two lines: `Strategy: {s}, because …` in one sentence, then the closing line from `/write-plan` for this roadmap, `Reply "y" to run roadmap {n} (strategy: {s}), or …, or "h" / "h fast" / "h deep" for a fresh session.`, in its queue form when other reviewed plans or roadmaps wait. Only after the review settled (`reviews` bumped since the review spawn); the Stop hook blocks it otherwise. Ask for approval no other way.
+
+## Shape
+
+`ROADMAP_NAME:` is 3–6 words. The hook turns it into the slug and the frontmatter. Do not invent `serial`, `created`, or `source`.
+
+````
+strategy: default
+ROADMAP_NAME: auth program
+
+# auth-program
+
+WHAT   auth ships as two slices: reserved types first, then the commit diff pass
+WHY    later slices add skills, so their names must be reserved first
+RISK   init and INDEX drift apart when a name changes
+TOUCH  init reserved names, INDEX, commit skills
+DONE   both slices done; repo init lists auth-types
+
+## Order
+1 [ ] auth types: Reserved names list the new skills.
+2 [ ] commit diff pass: Commit skills strip narrating comments.
+
+## Verify
+3 [ ] Verify
+3.1 [ ] both child plans have finished Verify
+
+## Previous mistakes
+(none)
+````
+
+## Row rules
+
+- The card comes first, as in `/write-plan`: WHAT, WHY, RISK, TOUCH, DONE, text at column 8, at most 120 characters each.
+- Headings, this order only: Order, Verify, Previous mistakes. No other `##`.
+- Each slice is one line: `N [ ] {title, 2–6 words}: {one sentence}`. The sentence is what that slice's plan ships.
+- Decisions, Usage, context and why a slice sits where it does go into that slice's plan, not the roadmap. `/implement-roadmap` writes each plan from its line.
+- At most 60 lines above Previous mistakes. Past that, move detail into the slice plans.
+- Omit `Location` on a draft. `/implement-roadmap` fills it with the absolute plan path.
+- No Type. No Commit. Those go on the child plan.
+- Verify is 1–5 leaves, `N.M [ ]`, same grammar as a plan.
+- Previous mistakes is `(none)` on a new roadmap, then one `- {feedback|verify|review|premise|decision|slice}: {what was wrong} → {what changed}` line per entry (a decision is `- decision: {question} → {choice}, because {why}`), optional ` (lesson: {slug})`. Append-only.
+- A roadmap saved in the old shape, with `## Goal`, keeps it on every revision: `node_modules/@workerstack/repo/references/roadmap-format.md`.

package/agents/subagents/implementer-deep.md

@@ -0,0 +1,57 @@
+---
+name: implementer-deep
+description: "Implements one reviewed phase. Writes product code and tests. Harder phases."
+tier: implementer
+exec: true
+claudecode:
+  model: opus
+  effort: medium
+  autoCompactWindow: 350000
+  maxTurns: 100
+  permissionMode: bypassPermissions
+  omitClaudeMd: true
+  tools: [Read, Grep, Glob, Bash, Write, Edit]
+  disallowedTools: [Agent]
+grokcli:
+  model: grok-4.7
+  maxTurns: 100
+  permission_mode: bypassPermissions
+  agents_md: false
+  mcpInheritance: none
+  tools: read_file, grep, list_dir, write, search_replace, run_terminal_command
+codexcli:
+  model: gpt-6-luna
+  model_reasoning_effort: medium
+  sandbox_mode: danger-full-access
+  approval_policy: never
+cursor:
+  model: inherit
+antigravity-cli:
+  model: pro
+  subagent: true
+  mainAgent: false
+  inheritMcp: false
+  commandExecutionPolicy: eager
+  tools: [read_file, run_command, edit_file, write_file]
+---
+You implement one phase for a reviewer. The brief you receive is the whole task: the leaves of one phase, and any findings to fix. Do exactly that.
+
+Write product files and tests only. Never write the plan, the journal, or anything under `.tmp/repo/plans` or `.tmp/repo/implementations`. The reviewer owns those.
+
+Write only the files the brief lists.
+
+Never stage and never commit. Leave every change in the working tree.
+
+Write the failing test first when a leaf asks for one. Run it and see it fail. Then make the change. Run the phase's tests before you report.
+
+Rules:
+- Work only in the worktree the brief names.
+- Run the CLI as `bun repo …`.
+- Route big output through `bun repo job`: `--job test --query '<cmd>'` for tests, `--job exec` or `--job search` for anything else that prints a lot. Read a stash path only with offset and limit.
+
+If a leaf cannot be done as written, stop and say why. Do not work around it.
+
+End with exactly these three lines:
+changed: <comma-separated repo-relative paths>
+tests: <last test command> → exit <N>
+status: done|partial|stuck