@workerstack/repo 0.0.0-stage → 0.1.0

package/agents/skills/principle-encode-lessons-in-structure/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: principle-encode-lessons-in-structure
+description: >-
+  Apply when you catch yourself writing the same instruction a second time, or
+  notice a recurring correction. Encode the rule as a lint, metadata flag,
+  runtime check, or script instead of more text. Use for
+  /principle-encode-lessons-in-structure.
+---
+# Encode Lessons in Structure
+
+If the lesson needs judgment and cannot be encoded, make the instruction more prominent and add an example of the failure mode.
+
+Slash `/principle-encode-lessons-in-structure` only. Not a session flag.
+
+**Corollary:** If the fix is structural, only use the structural fix. The instruction is the symptom.

package/agents/skills/principle-exhaust-the-design-space/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: principle-exhaust-the-design-space
+description: >-
+  Apply when facing a novel UI interaction or architectural decision with no
+  precedent in the codebase. Build 2-3 competing prototypes and compare side by
+  side before committing. Use for /principle-exhaust-the-design-space.
+---
+# Exhaust the Design Space
+
+It also applies to product design decisions where user experience depends on feel, not logic.
+
+Slash `/principle-exhaust-the-design-space` only. Not a session flag.

package/agents/skills/principle-experience-first/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: principle-experience-first
+description: >-
+  Apply when product, UX, or feature-scope tradeoffs come up. Choose user
+  delight over implementation convenience; ship fewer polished features over
+  more rough ones. Use for /principle-experience-first.
+---
+# Experience First
+
+When implementation convenience conflicts with user delight, choose delight.
+
+Slash `/principle-experience-first` only. Not a session flag.
+
+- Every feature, control, and option must be justified
+- Ship less, ship better (polished experience with three features beats rough one with ten)
+- Prototype before committing (design decisions are cheaper in throwaway HTML than production code)
+- Get the details right (transitions, alignment, spacing, feedback, error states)
+- Tighten the core loop (every feature should serve the central workflow or get out of the way)
+
+The user is whoever consumes the work. For a UI that is the end user. For a library or an internal API it is the colleague who imports it. The engineer who maintains the code next is a user too. Weigh their experience the same way, and explain impact from their perspective.
+
+Foundations should serve the experience. Foundational thinking governs the *sequence* of work. This principle governs the *target*.

package/agents/skills/principle-explain-the-number/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: principle-explain-the-number
+description: >-
+  Apply before you trust, report, or act on a number you measured: a speedup, a
+  regression, a throughput, a latency, or an eval result. Find what limits it,
+  and rule out that it measured something other than the work you think. Use for
+  /principle-explain-the-number.
+---
+# Explain the Number
+
+- **Ask "why not double?"** Name the resource or code path that bounds the result, such as a core, a lock, the disk, the network, or the load generator itself. Get it from a profile or from system counters taken during a run, then map it to source. A guess from reading the code is not a limiter. If you cannot say why the number is not twice as good, you do not know what you measured.
+- **List what else the number could be measuring, and rule out each one with evidence.** The usual suspects are errors, skipped or cached work, code that never ran, an untuned side (one left on default settings), noise, and a piece too small to matter end to end.
+- **Keep the evidence with the number.** Put the run count, the spread, and the limiter in the notes or a linked artifact.
+
+Slash `/principle-explain-the-number` only. Not a session flag.
+
+For a performance number, run a full measured procedure: name the limiter, check tuning, count errors, repeat, check end-to-end relevance, and confirm the work happened. For an eval result, ask the same of the trials: did every run do the task, does the gap hold across trials and models, and does the scenario matter.
+
+You skipped this when the evidence behind a number has no run count, no spread, or no named limiter, or when the time saved is larger than the time the changed piece took.
+
+Distinct from `/principle-prove-it-works`, which checks that an output is real.

package/agents/skills/principle-fix-root-causes/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: principle-fix-root-causes
+description: >-
+  Apply when debugging. Trace each symptom back to the first place the system
+  went wrong and fix it there. A guard is a fix only when the state it handles
+  is legitimate. Use for /principle-fix-root-causes.
+---
+# Fix Root Causes
+
+When debugging, fix the fault, not the place where it surfaced. The symptom is where a wrong state became visible. The root cause is the first place the system did something it should not do, or failed to handle a state it should handle.
+
+Slash `/principle-fix-root-causes` only. Not a session flag.
+
+**Why:** A symptom fix hides the evidence and leaves the fault free to surface somewhere else. Each one makes the system harder to reason about, because the code now carries a workaround for a bug that nobody named.
+
+**Pattern:**
+- Reproduce first.
+- Ask "why" at each step until the answer is a wrong decision in the code, not a consequence of an earlier one.
+- When stuck, instrument. Read the actual error and the actual state. Do not guess.
+- Ask whether the state that triggered the symptom is legitimate. If the system may be in that state, the code that broke on it is the root cause, and handling the state there is the fix. If the state should never exist, a check where it broke hides the bug. Find what produced the state. Guards, retries, swallowed errors, clamped values, and discarded state are the usual ways to hide a bug.
+- When something fails only after a restart, suspect persisted state first: config files, caches, lock files, serialized state.
+- Check for the pattern, not just the instance. Find every place with the same fault and fix them all.
+- If a workaround needs a paragraph-long comment to justify it, the code is wrong. Fix the code, not the comment.
+- If the deciding fact took a deep dig to find, propose the cheap, always-on signal that would have shown it at first look.

package/agents/skills/principle-foundational-thinking/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: principle-foundational-thinking
+description: >-
+  Apply before writing logic: choosing core types and data structures,
+  sequencing scaffold-vs-feature work, asking what concurrent actors share. Get
+  the data structures right so downstream code becomes obvious. Use for
+  /principle-foundational-thinking.
+---
+# Foundational Thinking
+
+**Structural decisions** protect option value. **Code-level decisions** protect simplicity.
+
+Slash `/principle-foundational-thinking` only. Not a session flag.
+
+**Data structures first.** Get the data shape right before writing logic. Define core types early, trace every access pattern, and choose structures that match the dominant paths.
+
+At code level, DRY the structure, not every line. Types and data models should converge. Three similar statements still beat a premature abstraction. Prefer explicit over clever. Test behavior and edge cases, not line counts.
+
+**Concurrency corollary.** Before sharing state between actors, ask "what happens if another actor modifies this concurrently?" If not "nothing", isolate.
+
+**Scaffold first.** If something helps every later phase, do it first. Ask "does every subsequent phase benefit from this existing?" CI, linting, test infrastructure, and shared types are scaffold. Sequence for option value: setup before features, tests before fixes. Keep commits small and single-purpose.
+
+Each increment should land a coherent abstraction or deepen one that exists. Do not spread a new capability across callers as special-case coordination.
+
+Subtraction comes before scaffolding. Remove dead code first, then lay foundations.

package/agents/skills/principle-guard-the-context-window/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: principle-guard-the-context-window
+description: >-
+  Apply when context is filling up: large outputs, long files, repeated reads,
+  fan-out planning. Route bulk to job and `.tmp/repo/` scratch; keep
+  summaries in the session, not raw payloads. Use for
+  /principle-guard-the-context-window.
+---
+# Guard the Context Window
+
+**Why:** Context overflow degrades reasoning quality, creates compression artifacts, and halts progress.
+
+Slash `/principle-guard-the-context-window` only. Not a session flag.
+
+**Pattern:**
+- **Size phases and cap scope.** Limit files per phase, set turn budgets, account for mechanism costs.

package/agents/skills/principle-laziness-protocol/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: principle-laziness-protocol
+description: >-
+  Apply when refactoring, evaluating diff size, or tempted to add abstractions,
+  layers, or signal threading. Bias toward deletion and the smallest change that
+  solves the problem. Use for /principle-laziness-protocol.
+---
+# Laziness Protocol
+
+- **Consolidate decisions.** Do not repeat the same choice in several places. Put it behind one source of truth and pass the result as a simple flag.
+- **Minimize the diff.** Make the smallest change that solves the problem. Fewer lines beat "elegant" boilerplate.
+
+Slash `/principle-laziness-protocol` only. Not a session flag.

package/agents/skills/principle-make-operations-idempotent/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: principle-make-operations-idempotent
+description: >-
+  Apply when designing commands, lifecycle steps, or processing loops that run
+  amid crashes, restarts, and retries. Converge to the same end state regardless
+  of partial prior runs. Use for /principle-make-operations-idempotent.
+---
+# Make Operations Idempotent
+
+Design operations so they converge to the correct state regardless of how many times they run or where the previous run stopped. Every state-mutating operation should answer: "What happens if this runs twice? What happens if the previous run crashed halfway?"
+
+Slash `/principle-make-operations-idempotent` only. Not a session flag.
+
+**Why:** Commands, lifecycle operations, and processing loops run where crashes, restarts, and retries are normal. If partial state changes the next run's outcome, every restart becomes a debugging session.
+
+**The idea:** derive each step from the state that exists, not from what the previous run meant to do. Read the current state, compare it to the goal, and apply only the difference. A step written this way is safe to repeat, because a repeat finds nothing left to do.
+
+Anything a run leaves behind, such as a lock, a temporary file, a half-written record, or a claimed job, must be recognizable as stale by the next run. Judge staleness by evidence that stays true wherever the previous run could have stopped, not only in the common case. A marker that the next run cannot judge turns every crash into manual cleanup. For example, write to a temporary path and rename it into place, or compare artifacts by content instead of by creation order.
+
+**The test:**
+1. What happens if this runs twice in a row?
+2. What happens if the previous run crashed at every possible point?
+3. Does re-execution converge to the same end state?
+
+If any answer is "it depends on what state was left behind," the operation needs a reconciliation step.

package/agents/skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: principle-migrate-callers-then-delete-legacy-apis
+description: >-
+  Apply when introducing a new internal API while old callers still exist.
+  Migrate callers and delete the old API in the same wave instead of preserving
+  compatibility layers. Use for
+  /principle-migrate-callers-then-delete-legacy-apis.
+---
+# Migrate Callers Then Delete Legacy APIs
+
+- Update tests to assert the new contract, and delete tests that only protect pre-refactor implementation details
+
+Slash `/principle-migrate-callers-then-delete-legacy-apis` only. Not a session flag.
+
+**When this applies:**
+- No external users depend on backward compatibility
+- The project can absorb coordinated breaking changes
+- The new API is part of a simplification or refactor initiative

package/agents/skills/principle-minimize-reader-load/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: principle-minimize-reader-load
+description: >-
+  Apply when reviewing or shaping code that's hard to trace. Count layers
+  between question and answer, and hidden state in the reader's head; collapse
+  one-caller wrappers and shrink mutable scope. Use for
+  /principle-minimize-reader-load.
+---
+# Minimize Reader Load
+
+Maintainability is the work a reader must do to understand code. Track two axes: **layers to trace** (indirections between the question and the answer) and **state to hold** (hidden or mutable context the reader must keep in their head). LOC, cyclomatic complexity, and "clean architecture" are proxies. Reader load is the thing that matters. The two axes are independent. A flat file with 50 globals can be as hard to reason about as a 6-layer adapter stack. Guard both. This is the human analog of `/principle-guard-the-context-window`. Working memory is finite for readers too.
+
+Slash `/principle-minimize-reader-load` only. Not a session flag.
+
+- **Collapse layers** that cost more than they save: wrappers with one caller, adapters with no second implementation, speculative indirection that was never needed. Inline them.
+- **Make adjacent layers change the abstraction.** A layer that repeats the same methods and arguments adds reader load without compression. Collapse pass-through layers.
+- **Demand interface compression.** A broad interface that hides little complexity makes readers learn both the surface and the implementation. Prefer boundaries that hide meaningful decisions.
+- **Shrink state scope:** prefer pure functions (returns over mutations), locals over fields, fields over module state, and module state over globals. Derive instead of sync.
+- **Name the invariant at the boundary,** not in every consumer, so the reader learns it once.
+- Before adding a layer or a piece of state, ask: does it reduce reader load elsewhere by at least as much?
+
+**The test:** can a new reader answer "where does X come from?" and "what can change X?" in under 30 seconds? If not, cut layers or cut state.

package/agents/skills/principle-model-the-domain/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: principle-model-the-domain
+description: >-
+  Apply when writing stateful logic, or when code branches a lot or repeats a
+  shape assumption across files. Use for /principle-model-the-domain.
+---
+# Model the Domain
+
+Encode the real domain in a data structure instead of scattering it across conditionals. A structure that matches the domain makes invalid states unrepresentable and deletes branches. Choosing it at write time is cheap. Recovering it later reads as a refactor and gets deferred.
+
+Slash `/principle-model-the-domain` only. Not a session flag.
+
+Reach for:
+
+- A state machine instead of scattered booleans, phases, or lifecycle checks.
+- A typed model instead of loose parameters or repeated shape assumptions.
+- A map, registry, lookup table, or discriminated union instead of branching spread across files.
+- A reducer or command/event model instead of ad hoc state mutations.
+- A module organized around one body of domain knowledge instead of a sequence such as load, validate, transform, and save. Execution order is not ownership.
+- A small module boundary that gathers repeated behavior, ownership, or invariants.
+- A queue, cache, index, graph, tree, or normalized collection where the access pattern calls for it.
+- Any other structure that fits. When none fits, work out what the code must never allow and how the data gets read, then find the structure that encodes exactly that.
+
+Do not force an abstraction. Prefer boring code if the current shape is already clear, local, and unlikely to grow. Be skeptical of an abstraction that adds indirection without removing branches, duplicated rules, invalid states, or lifecycle risk.
+
+The sign that you skipped this is a new feature that grows an existing if/else chain by one more branch, or a second boolean that must stay in sync with the first. Temporal decomposition is another sign. Phase-named modules repeat the same domain rules across steps.

package/agents/skills/principle-never-block-on-the-human/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: principle-never-block-on-the-human
+description: >-
+  Apply when tempted to ask 'should I do X?' on reversible work. Use for
+  /principle-never-block-on-the-human.
+---
+# Never Block on the Human
+
+Don't ask preference on reversible execution. Make a reasonable call, do the work, and show the result. Stop for plan approval (scope.md), real blockers, and irreversible actions (force-push, delete production data, send external messages). A `locked` or `in-progress` roadmap that `/implement-roadmap` is running is already that approval.
+
+Slash `/principle-never-block-on-the-human` only. Not a session flag.
+
+- Proceed, then present. Do the work, show the result. Don't ask "should I do X?" Do X, explain why.
+- Make the system self-healing. When you notice a problem, log it and fix it in the next round.
+- Irreversible actions (force-push, delete production data, send external messages) still require confirmation.
+- Reversible actions (write code, edit notes, split tasks) should proceed without blocking.
+- Product direction comes from the human. Execution should not block.

package/agents/skills/principle-outcome-oriented-execution/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: principle-outcome-oriented-execution
+description: >-
+  Apply during planned rewrites and migrations with explicit phase boundaries.
+  Converge on the target architecture; don't preserve smooth intermediate states
+  with throwaway compatibility code. Use for
+  /principle-outcome-oriented-execution.
+---
+# Outcome-Oriented Execution
+
+Optimize for the intended, verifiable end state rather than preserving smooth intermediate states.
+
+Slash `/principle-outcome-oriented-execution` only. Not a session flag.
+
+**Why:** Keeping every intermediate step fully stable often creates temporary compatibility code that becomes long-lived debt. Converge on the target architecture and prove correctness at explicit verification boundaries.
+
+**Core rule:**
+- Prioritize end-state integrity over transitional stability
+- Intermediate breakage is acceptable when it is planned, scoped, and reversible
+
+**Guardrails:**
+- Use this for planned rewrites and migrations with explicit phase boundaries
+- Declare where temporary breakage is acceptable
+- Keep high-signal checks for actively touched areas while migrating
+- Require full static and runtime verification at plan completion

package/agents/skills/principle-prove-it-works/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: principle-prove-it-works
+description: >-
+  Apply after completing a task, before declaring done. Verify against the real
+  artifact (run the feature, read the actual value, inspect the diff), not a
+  proxy, self-report, or 'it compiles.'. Use for /principle-prove-it-works.
+---
+# Prove It Works
+
+Verify every task output by checking the real thing directly. Do not infer from proxies, self-reports, or "it compiles."
+
+Slash `/principle-prove-it-works` only. Not a session flag.
+
+**Why:** Unverified work has unknown correctness. Indirect verification (file mtimes, output freshness, agent self-reports, cached screenshots) feels cheaper than direct observation. Acting on a wrong inference costs far more than checking the source.
+
+Check the real thing, not a proxy:
+- Check process liveness directly, not indirectly through derived state
+- Read the actual value, not a cached or derived representation
+- When verification fails, suspect the observation method before suspecting the system
+
+## Script the check when you can
+
+The strongest proof is a deterministic script that re-runs the same comparison, not a one-time eyeball. Write the script, run it, and keep its output as an artifact a reviewer can re-run instead of trusting your word.
+
+Keep the artifact visible for the human. Commit it only for large or complex work where the trail has to be auditable later, like a big port or migration.

package/agents/skills/principle-redesign-from-first-principles/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: principle-redesign-from-first-principles
+description: >-
+  Apply when integrating a new requirement into an existing design. Use for
+  /principle-redesign-from-first-principles.
+---
+# Redesign From First Principles
+
+When integrating a change, don't bolt it onto the existing design. Redesign as if the requirement had been a foundational assumption from the start.
+
+Slash `/principle-redesign-from-first-principles` only. Not a session flag.
+
+- Read all affected files and understand the current design
+- Ask: "if we were writing this from scratch with this new requirement, what would we build?"
+- Propagate the change through every reference: types, docs, examples, rationale sections
+- Think about the whole redesign, then deliver it incrementally
+
+This is the method for preserving option value when integrating changes into an existing design.

package/agents/skills/principle-separate-before-serializing-shared-state/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: principle-separate-before-serializing-shared-state
+description: >-
+  Apply when concurrent actors might write to the same file, branch, key, or
+  state object. Eliminate the sharing first; serialize structurally only when
+  one shared writer is a real invariant. Use for
+  /principle-separate-before-serializing-shared-state.
+---
+# Separate Before Serializing Shared State
+
+When concurrent actors might share mutable state, first ask whether they need the same mutable object. If not, eliminate the sharing. When sharing is real, enforce serialization structurally: lockfiles, sequential phases, exclusive ownership. Instructions and conventions are not concurrency control.
+
+Slash `/principle-separate-before-serializing-shared-state` only. Not a session flag.
+
+**Why:** Concurrent writes to shared state create race conditions that are intermittent, hard to reproduce, and expensive to debug.
+
+**Pattern:**
+1. **Identify shared mutable state** (files both read and write, branches both push to, APIs both define and consume).
+2. **Default: eliminate the shared write target.** Ask: do these actors need one canonical object, or are they publishing independent facts? Give each actor its own owned file, key, branch, or state directory, and merge only at the read/reporting boundary. Two workers writing their own `lastX` field into one `state.json` is still shared mutation. `indexer-state.json` + `metrics-state.json` is not.
+3. **Only when one shared write target is a real invariant, serialize access structurally** (lockfiles, sequential phases, single-writer actor, or atomic compare-and-swap). Treat "we need a lock" as a design smell to check, not as the default answer.

package/agents/skills/principle-sequence-verifiable-units/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: principle-sequence-verifiable-units
+description: >-
+  Apply to multi-step work (sweeps, migrations, runs of similar edits) and to
+  how you stack commits and PRs. Break work into small units that each end in a
+  verifiable state, check each before the next, and order delivery so the
+  sequence proves itself to a reviewer. Use for
+  /principle-sequence-verifiable-units.
+---
+# Sequence work into verifiable units
+
+Order work as a sequence of small units, each ending in a state you can check, and don't advance until the current one is green.
+
+Slash `/principle-sequence-verifiable-units` only. Not a session flag.
+
+**Why:** A break caught at the unit that caused it is cheap to localize. A break caught after a batch is buried, and you have already built further on a broken base. Sequencing those same units into a delivery a reviewer can replay turns "trust me" into "watch it go red, then green."
+
+**Execution.** In a sweep, migration, or any run of similar edits, verify each change before starting the next. Each unit is a before/after bracket: known-good state, one change, run the check, then proceed. Rebase onto clean trunk first so every check measures against the real baseline. When a lever does the edits, the per-unit check is nearly free. Run it anyway.
+
+**Delivery.** Stack commits and PRs in the order that proves the work. The canonical shape is the failing test first, then the fix on top. A plan with one `commit:` is one unit: its failing test and the fix land in that commit. A roadmap slice is that plan. Other story orders are a subtraction before the reshape, a baseline capture before the treatment, the scaffold before the feature. Each commit lands on its own and the sequence reads as an argument.
+
+The sequencing complement to `/principle-prove-it-works`, which keeps each check real, and `/principle-build-the-lever`, which makes the per-unit check cheap.

package/agents/skills/principle-subtract-before-you-add/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: principle-subtract-before-you-add
+description: >-
+  Apply when sequencing an addition, refactor, or rewrite. Remove dead code,
+  redundant validators, and stub references first, then build on the simpler
+  base. Use for /principle-subtract-before-you-add.
+---
+# Subtract Before You Add
+
+When evolving a system, remove complexity first, then build. Default to subtraction.
+
+Slash `/principle-subtract-before-you-add` only. Not a session flag.
+
+Make simplification a continual investment. Leave the design slightly simpler and more capable behind the same or smaller surface than you found it.
+
+- Sequence removal before construction
+- Cut before you polish (get to the minimum before investing in quality)
+- Design for observed usage, not speculative edge cases
+- No speculative validators, parsers, or guards beyond what the spec demands
+- Simplify prompts (remove redundant instructions, excessive templates)
+- When a reference has no novel content, delete it rather than leaving a stub

package/agents/skills/principle-test-behavior-not-implementation/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: principle-test-behavior-not-implementation
+description: >-
+  Apply when you write, change, or keep a test. Assert what the code's users can
+  observe, so that the test fails when that behavior breaks and keeps passing
+  when only the internals change. Use for
+  /principle-test-behavior-not-implementation.
+---
+# Test Behavior, Not Implementation
+
+A test is a claim about what the code does for its users: a caller, an end user, or another service. Behavior is what those users can observe through the interface they use. That includes return values, errors, state they can read back, and effects on systems outside the code, such as a request sent, a row written, or a message emitted. Implementation is what they cannot observe: private helpers, internal call order, intermediate data, and which internal collaborator did the work.
+
+Slash `/principle-test-behavior-not-implementation` only. Not a session flag.
+
+Judge each test against two imagined edits:
+
+- **Break the behavior.** Make the code return a wrong value, skip an effect, or do the effect twice. If the test still passes, it proves nothing. The usual causes are an assertion looser than the contract, an expected value computed by the code under test, a restated constant or prompt string that never runs the code that reads it, and an assertion on data that the test built itself.
+- **Change the internals.** Keep every observable result the same and restructure the code underneath. If the test now fails, it is pinned to the implementation. It will need a rewrite on every refactor and still catches no bug.
+
+Keep a test that catches the first edit and survives the second. Rewrite or delete the rest. To write a test that does both, drive the code through its users' interface with a concrete input. Derive the expected value from the requirement, not from a run of the code. Assert what the contract promises, no less and no more.
+
+The contract decides, not the shape of the assertion. When "an empty cart never charges" is the promise, an assertion that the payment client got no call is behavior. Pair it with a case where the charge happens, so that the test shows it can see a call. The payload that a mocked external service receives is behavior, because that service observes it. A call to an internal helper is implementation, because no user can see it. An empty list is the exact answer when no record matches, and a hollow check when the test only needs some result. An exact error message pins wording that no caller reads. The error type that callers branch on is the contract.
+
+A test can pin an invariant instead of a call, such as a key that must exist in two tables or a compile-time type check. The invariant is the behavior.

package/agents/skills/principle-type-system-discipline/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: principle-type-system-discipline
+description: >-
+  Apply when designing types, reviewing a function signature, or writing code in
+  any statically-typed language. Make illegal states unrepresentable, brand
+  semantic primitives, parse external data at boundaries, exhaust variants,
+  derive from authoritative schemas. Use for /principle-type-system-discipline.
+---
+# Type System Discipline
+
+Make the compiler reject impossible states, mismatched primitives, and unhandled variants. Prefer defining errors and special cases out of existence over proliferating handlers. For TypeScript syntax, see `/typescript-best-practices`.
+
+Slash `/principle-type-system-discipline` only. Not a session flag.
+
+- **Brand semantic primitives.** `UserId` and `OrderId` are strings underneath but should not be interchangeable. Give each its own type, such as a branded intersection in TypeScript or a newtype elsewhere. Validate once at creation, trust the type downstream. If two arguments share a primitive type but mean different things, brand them.
+- **External data is untyped until parsed.** RPC payloads, JSON, IPC messages, CLI args, config files, environment variables, database rows. Have a parse function at every boundary that turns unstructured input into the typed model. `/principle-boundary-discipline` says where to put validation.
+- **Derive types from authoritative schemas.** When a protocol buffer, OpenAPI spec, GraphQL schema, database migration, design-token file, or another file owns a shape, derive from it instead of hand-rolling a parallel type. See `/principle-encode-lessons-in-structure`.

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

@@ -0,0 +1,28 @@
+---
+name: review-plan
+description: Review a plan in a fresh agent before approval. Use for /review-plan.
+---
+# review-plan
+
+You review one plan under `.tmp/repo/plans/` that someone else wrote. You start with no context from the writing session, and that is the point: judge the file, not the reasoning behind it. Format: `node_modules/@workerstack/repo/references/plan-format.md`. Lessons: `node_modules/@workerstack/repo/references/lessons.md`.
+
+Slash `/review-plan {n|path}` only. Not a session flag. `/write-plan` runs it in a fresh agent after every write or revision. Run it yourself on any plan.
+
+Read-only. Write nothing: not the plan, not a lesson, not a journal. The writer applies what it accepts and bumps the plan's `reviews` count in that save.
+
+Rounds repeat: the first runs after `/write-plan`, another after each revision, and anyone can run one by hand. The count proves a round ran and was settled, not that it was good. A plan cannot move to `in-progress` until `reviews` is at least 1.
+
+Scripts already enforce the format, the card's shape, the 100-line cap, reads-only phases, disjoint `parallel:` lists, the append-only `## Previous mistakes`, and the lesson citations. Do not re-check those. Check what a script cannot:
+
+1. Read the plan in full.
+2. Read its `## Previous mistakes`. Flag any leaf that brings a recorded mistake back.
+3. Run `bun repo lessons match` on the paths the plan names (repo-relative or absolute; `match` is read-only and runs from the root). Read each matched lesson. Flag a lesson cited in Watch-outs that no leaf acts on.
+4. Read each principle skill the plan names. Flag a leaf that goes against it.
+5. Check the type row in `node_modules/@workerstack/repo/references/scope.md` ## Types and its ## Facts: a missing failing-test leaf, a named principle with no Read leaf, a Read leaf outside the phase it gates, or a named check dropped without a reason.
+6. Flag a leaf that needs more planning before someone can do it: an open choice, a vague target, or a path that does not exist.
+7. Flag a file the Steps must change that no leaf or allowlist names, and a caller or consumer the change can break that no leaf covers.
+8. Compare `## Usage` with Steps. Flag each new or changed command, flag, output, error message, or file a person or agent touches that Usage does not show, a changed one shown without its before, and a `No visible change:` line on a plan that changes one.
+9. Compare the card with Goal and Steps. Flag a `WHAT` or `DONE` that Goal and Verify do not back, a `TOUCH` that misses a file the Steps change, and a `RISK` no leaf or Watch-out covers.
+10. For each `(parallel: …)` phase, flag a path its leaves name that is not in its list.
+
+Reply with at most 10 findings, most severe first, one line each: `{leaf id or section}: {problem}; {fix}`. With nothing to flag, reply `no findings`. No praise and no summary.

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

@@ -0,0 +1,28 @@
+---
+name: review-roadmap
+description: Review a roadmap in a fresh agent before lock. Use for /review-roadmap.
+---
+# review-roadmap
+
+You review one roadmap under `.tmp/repo/roadmaps/` that someone else wrote. You start with no context from the writing session, and that is the point: judge the file, not the reasoning behind it. Format: `node_modules/@workerstack/repo/references/roadmap-format.md`. Lessons: `node_modules/@workerstack/repo/references/lessons.md`.
+
+Slash `/review-roadmap {n|path}` only. Not a session flag. `/write-roadmap` runs it in a fresh agent after every write or revision. Run it yourself on any roadmap.
+
+Read-only. Write nothing: not the roadmap, not a plan, not a lesson. The writer applies what it accepts and bumps the roadmap's `reviews` count in that save.
+
+Rounds repeat: the first runs after `/write-roadmap`, another after each revision, and anyone can run one by hand. The count proves a round ran and was settled, not that it was good. A roadmap cannot move to `locked` until `reviews` is at least 1.
+
+Scripts already enforce the format and the append-only `## Previous mistakes`. Do not re-check those. Check what a script cannot:
+
+1. Read the roadmap in full.
+2. Read its `## Previous mistakes`. Flag a slice that brings a recorded mistake back.
+3. Run `bun repo lessons match` on the paths the roadmap names (repo-relative or absolute; `match` is read-only and runs from the root). Read each matched lesson. Flag a slice that walks into one and no slice plan can avoid it.
+4. Read `principle-sequence-verifiable-units`. Flag a slice that cannot be verified on its own, or that needs something a later slice ships.
+5. Flag a slice that is really two plans, or half of one that should merge with its neighbor.
+6. Flag a slice sentence too vague to write a plan from: an open choice, a vague target, or a path that does not exist.
+7. Compare the card with the slices: flag a WHAT or DONE no slice ships, a RISK no slice handles, and a TOUCH that misses what the slices change.
+8. Flag a Verify gate no one can run, and a DONE no Verify gate proves.
+
+A roadmap saved in the old shape (with `## Goal`) keeps the old checks as well: flag a Decision with no rejected alternative, a slice Goal or Why that contradicts a Decision, a slice that walks into a matched lesson with no Watch-out, a program Goal no Verify gate proves, and compare `## Usage` with the slices: each new or changed command, flag, output, error message, or file it does not show, a changed one shown without its before, and a `No visible change:` line on a roadmap that changes one.
+
+Reply with at most 10 findings, most severe first, one line each: `{slice number or section}: {problem}; {fix}`. With nothing to flag, reply `no findings`. No praise and no summary.

package/agents/skills/show-me/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: show-me
+description: 'Restate the current proposal as a concrete before and after: commands, output, errors, files.'
+---
+This reply only: restate the current proposal (the plan, roadmap, or change under discussion) as a concrete before and after. Not a mode switch or session flag. After this reply, revert to output.md.
+
+Show what the person sees, not how it works:
+- Before and after, side by side or one under the other, in fenced blocks.
+- The exact commands they type, the output and errors they get back, and the files that change.
+- No abstractions and no internal names they did not use.
+- When the plan has a Usage section, take it from there. Do not invent what it does not show.
+
+Example Usage line:
+
+```
+Before: `notes export --json` → error: unknown flag   After: prints [{"id":1,…}]   Files: src/cli.ts, src/export.ts
+```
+
+When a reviewed plan or roadmap waits for approval, end with the exact closing line `/write-plan` defines, ending ` or "h" / "h fast" / "h deep" for a fresh session.` Otherwise add nothing extra.
+
+Slash `/show-me` only.

package/agents/skills/speak/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: speak
+description: >-
+  Text-to-speech via bun repo speak (ElevenLabs or OpenAI).
+  Output only.
+---
+# speak
+
+When the user wants spoken audio, run `bun repo speak`. Spec: `node_modules/@workerstack/repo/references/speak.md`. Output only (text → mp3). Do not record a mic. Do not transcribe.
+
+`whoami` · `voices` · `say --text T [--provider elevenlabs|openai] [--voice ID] [--out path] [--play]`.
+
+Auth: `ELEVENLABS_API_KEY` or `OPENAI_API_KEY` or `~/.workerstack/speak.json`. Do not commit the key. Default voices: ElevenLabs George (`JBFqnCBsd6RMkjVDRZzb`), OpenAI `coral`.
+
+If the CLI exits non-zero, print its message. Lines with `setup:` are for the user — show that command. Tell them to run `bun repo setup speak` (or `bun repo setup`) in their terminal. Do not dump JSON. Do not invent a key. Spec: `node_modules/@workerstack/repo/references/speak.md` `node_modules/@workerstack/repo/references/setup.md`.

package/agents/skills/su/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: su
+description: 'Short status update: done, next, and blockers or on-track ETA.'
+---
+This reply only: a status update in two to four short lines. No process narration.
+
+- Done: what is finished. Flag anything unverified.
+- Next: the immediate next step.
+- Health: if stuck, blocked, broken, or slipping, say so plainly. Otherwise "On track" with a rough ETA (minutes, ~1h, end of session).
+
+Never soften bad news or claim progress not made.

package/agents/skills/teach/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: teach
+description: >-
+  Explain a body of work plainly so a person actually understands it. Dig into
+  how it works and why it is that way, then weave that into one clear
+  explanation. Use for /teach, 'teach me this', 'help me really understand X',
+  'explain this change or subsystem to me'.
+---
+# Teach
+
+**You explain what a thing is, how it works, and why it's built that way, in one plain account at the person's pace. The goal is that they understand it, not that you change anything.**
+
+Slash `/teach` only. Not a session flag. Not `/explain` (that is a longer recap of this session's work).
+
+Get your bearings on what the work is and what it touches, then find how it works and why it's that way. Those are real reads of the code and of the history, not a restatement of the question. Blend what they find into one plain explanation, lead with what matters to the person, and go deeper when they ask. Reword freely for teaching, with one exception. Keep confidence language from the history intact (its hedges are findings, not style).
+
+1. Decide the few things they should walk away understanding. Choose them from why they're asking (about to change it, reviewing it, debugging it, new to it) and what they already know, both read from the conversation, not quizzed out of them. Skip what they plainly already know. Put the depth where their question is.
+2. Dig, don't invent. Read the code yourself to get oriented, then work out how it works (runtime path, where things live, gotchas) and why it is that way (`git log` / `git blame`, `gh pr view` when a PR number is in the history, tickets when they exist). Do both in parallel when the question is a subsystem. Match the size to the question. One side may be enough for a small change. Keep the history sweep narrow by default. Put the narrowing in the ask itself (a scoped question, git plus a source or two) and record what you skipped, and widen it only when the reasons are the point.
+3. Start with a plain definition. Name the thing and say what it is in general terms, the way a senior engineer would say it out loud, with its common name if it has one. Then tie it to the case in front of you ("in X, we use this to ...") and build from there: how it works, the deeper reasons, the edge cases. For each part, explain the idea so it clicks: the problem it solves and how it actually works. Walk through what happens as the person does the thing (opens a long chat, scrolls up) when that is what makes it land. Listing functions and constants is reference, not teaching. Don't print framing labels ("the one idea to hold onto", "the thing to walk away with", "the key insight", "at its core", "TL;DR"). Give the smallest complete answer first, a sentence or two, not a dense paragraph, then stop. Add layers when they ask. Never a wall of text.
+4. Keep it a conversation, not a lecture or a performance. Offer to go deeper or move on, and follow their lead. No quizzes. No pacing theater. Don't print "Pause", don't ask them to say it back, don't announce "the sentence to nail", and don't flag a part as important or hard ("here is the part worth slowing down on", "this is the tricky part", "here is where it gets interesting"). Just say it. When you would pause, stop and let them respond. Running one-shot with no live human, deliver it cleanly and put any offer to go deeper at the end.
+5. Show, don't only tell, and build the picture up diagram by diagram. Open the diff, the code, or the debugger when that is the fastest way to land it. Draw when a picture lands faster than words. For anything with three or more moving parts, do not draw one diagram with all of them at once. Draw a short series instead, where each diagram redraws the last and adds a single part, so the reader watches the system assemble. A single all-at-once diagram, especially one saved for the end, is a reference, not teaching. Concretely, to teach a flow from A to B to C, draw it three times. First A to B. Then redraw and add C. Then redraw and add the return edge or the next piece. Match the medium to the idea, and use both kinds when both help. A mermaid diagram fits a flow or structure where the labels carry the meaning. When the idea is spatial, like layout, overlap, scroll position, or a before and after, and the harness has an image-generation tool, draw it marker-on-whiteboard style with a few short labels, since image models garble long text. Generate that picture, don't settle for describing it in words. The build-up rule holds for generated images too. A single simple point needs no figure.
+
+Write every response through `/unslop`, in plain spoken English, the way you'd explain it to a colleague. Be tight, not terse. Cut filler and hedging, keep the part that makes it click. State the concrete mechanism, not a metaphor, a framing, or a preview of what is coming. This is the target density: "Virtualization runs in two parts, one for rendering and one for loading from disk. When an item scrolls out past the buffer, both its DOM node and its in-memory data are evicted." Normal sentence case, not all-lowercase. No em dashes. Prefer periods over commas. Keep each sentence to one or two commas. If clauses pile up, split them into separate sentences. Give each concept one name and keep it. Avoid mirror sentences ("A without B, or B without A") and tidy closers ("the rest follows", "it all falls out"). The words in these steps are directions to you, not labels to print. Don't echo the structure as headers or stock phrases.
+
+**Reply:** the explanation itself, never a report about what you did or delivered. Lead with the main point, then the plain account of what it is, how it works, and why, and the threads worth chasing next.