ramstack 0.1.0

package/skills/principle-migrate-callers-then-delete-legacy-apis/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Migrate Callers Then Delete Legacy APIs"
+  short_description: "Migrate callers and delete the old API together"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-minimize-reader-load/README.md

@@ -0,0 +1,17 @@
+# Minimize reader load
+
+Maintainability is the work a reader does to understand code. Minimize it.
+
+## When it applies
+
+- You review or shape code that is hard to trace.
+- You count layers between a question and its answer.
+- You notice hidden or mutable state the reader must track mentally.
+
+## The rule
+
+Track two axes: layers to trace and state to hold. Collapse wrappers with one caller, pass-through layers, and adapters with no second implementation. Shrink state scope by preferring pure functions, locals over fields, and derivation over synchronization. A new reader should answer "where does X come from?" in under 30 seconds.
+
+## Related
+
+- [Full rule](SKILL.md)

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

@@ -0,0 +1,23 @@
+---
+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."
+disable-model-invocation: true
+---
+
+# Minimize Reader Load
+
+Maintainability is the work a reader must do to understand code. Track two axes:
+1. **Layers to trace.** How many indirections sit between the question and the answer.
+2. **State to hold.** How much hidden or mutable context the reader must keep in their head.
+
+**Why:** Code is read far more than it is written. 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 [Guard the Context Window](../principle-guard-the-context-window/SKILL.md): working memory is finite for readers too.
+
+**The pattern:**
+- **Collapse layers** that do not earn their keep: wrappers with one caller, adapters with no second implementation, indirection introduced for a future that never came. 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 this reduce reader load somewhere else 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/skills/principle-minimize-reader-load/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Minimize Reader Load"
+  short_description: "Collapse layers and hidden state for readers"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-model-the-domain/README.md

@@ -0,0 +1,17 @@
+# Model the domain
+
+Encode the real domain in a data structure instead of scattering it across conditionals.
+
+## When it applies
+
+- Writing stateful logic, or code that branches heavily.
+- Code repeats a shape assumption across files.
+- A new feature grows an existing if/else chain by one branch.
+
+## The rule
+
+Reach for the structure that fits: a state machine instead of scattered booleans, a typed model instead of loose parameters, a map or discriminated union instead of branching spread across files, a reducer instead of ad hoc mutations. Do not force an abstraction when the current shape is clear, local, and unlikely to grow. The tell that you skipped this is a second boolean that must stay in sync with the first.
+
+## Related
+
+- [Full rule](SKILL.md)

package/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. Encode the domain in a structure instead of scattered conditionals."
+disable-model-invocation: true
+---
+
+# Model the Domain
+
+Encode the real domain in a data structure instead of scattering it across conditionals.
+
+**Why:** Scattered booleans, repeated shape assumptions, and branching spread across files are accidental complexity. 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.
+
+**Reach for structures like these:**
+
+- A state machine instead of scattered booleans, phases, or lifecycle checks.
+- A typed object/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 data access pattern calls for it.
+- Any other structure that fits. The list above covers the common cases only. 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 tell 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 tell. Phase-named modules repeat the same domain rules across steps.

package/skills/principle-model-the-domain/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Model the Domain"
+  short_description: "Encode the domain in a structure, not conditionals"
+policy:
+  allow_implicit_invocation: false

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

@@ -0,0 +1,16 @@
+# Never block on the human
+
+Proceed with reversible work, present the result, and let the human course-correct after the fact.
+
+## When it applies
+
+- Tempted to ask "should I do X?" on reversible work.
+- The agent could infer intent from context but pauses to confirm.
+
+## The rule
+
+Code is cheap. Waiting is expensive. Do the work, show the result, and explain why. Reserve confirmation for irreversible actions: force-push, data deletion, external messages. Reversible actions (write code, edit notes, split tasks) should proceed without blocking. Product direction comes from the human. Execution should not.
+
+## Related
+
+- [Full rule](SKILL.md)

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

@@ -0,0 +1,23 @@
+---
+name: principle-never-block-on-the-human
+description: "Apply when tempted to ask 'should I do X?' on reversible work. Proceed, present the result, let the human course-correct after the fact; reserve confirmation for irreversible actions."
+disable-model-invocation: true
+---
+
+# Never Block on the Human
+
+The human supervises asynchronously. Agents must stay unblocked: make reasonable decisions, proceed, and let the human course-correct after the fact. Code is cheap. Waiting is expensive.
+
+**Why:** Every permission pause stalls the pipeline and makes the human the bottleneck. Since code changes are reversible and reviewable, a wrong decision usually costs less than blocking.
+
+**Pattern:**
+- **Proceed, then present.** Do the work, show the result. Don't ask "should I do X?" Do X, explain why.
+- **Reserve questions for genuine ambiguity.** Ask only when you truly cannot infer intent from context.
+- **Make the system self-healing.** When you notice a problem, log it and fix it in the next round.
+- **Supervision is async.** The human reviews plans, diffs, and changes on their own schedule. Design workflows for review-after-the-fact.
+- **Code is cheap, attention is scarce.** A wrong implementation costs minutes to fix. A blocked agent costs the human's attention to unblock.
+
+**Boundaries:**
+- **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/skills/principle-never-block-on-the-human/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Never Block on the Human"
+  short_description: "Proceed on reversible work without waiting"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-outcome-oriented-execution/README.md

@@ -0,0 +1,16 @@
+# Outcome-oriented execution
+
+Optimize for the intended end state, not smooth intermediate states.
+
+## When it applies
+
+- Planned rewrites and migrations with explicit phase boundaries.
+- Throwaway compatibility code threatens to become long-lived debt.
+
+## The rule
+
+Converge on the target architecture and prove correctness at explicit verification boundaries. Intermediate breakage is acceptable when planned, scoped, and reversible. Declare where temporary breakage is acceptable. Require full static and runtime verification at plan completion.
+
+## Related
+
+- [Full rule](SKILL.md)

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

@@ -0,0 +1,22 @@
+---
+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."
+disable-model-invocation: true
+---
+
+# Outcome-Oriented Execution
+
+Optimize for the intended, verifiable end state rather than preserving smooth intermediate states.
+
+**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
+- Always run final verification before declaring done
+
+**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/skills/principle-outcome-oriented-execution/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Outcome-Oriented Execution"
+  short_description: "Converge on the target architecture, skip throwaways"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-prove-it-works/README.md

@@ -0,0 +1,18 @@
+# Prove it works
+
+Verify every task output by checking the real thing directly, not a proxy or self-report.
+
+## When it applies
+
+- After completing a task, before declaring done.
+- Verifying delegated work from a subagent.
+- Tempted to rely on "it compiles" or a cached representation.
+
+## The rule
+
+Check the real artifact: run the feature, read the actual value, inspect the diff. Process liveness is checked directly, not through derived state. When verification fails, suspect the observation method before suspecting the system. For delegated work, inspect the output artifact (git diff, file contents, runtime behavior), not the delegate's summary. Script the check when you can, so a reviewer can rerun it.
+
+## Related
+
+- [Full rule](SKILL.md)
+- [show-me-your-work](../show-me-your-work/) (committed trail for large work)

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

@@ -0,0 +1,33 @@
+---
+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.'"
+disable-model-invocation: true
+---
+
+# Prove It Works
+
+Verify every task output by checking the real thing directly. Do not infer from proxies, self-reports, or "it compiles."
+
+**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.
+
+**Pattern:** After completing any task, ask: "how do I prove this actually works?"
+
+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
+
+Code and features:
+1. Build it (necessary but not sufficient)
+2. Run it and exercise the actual feature path
+3. Check the full chain: does data flow from input to output?
+4. For integrations, test the full communication path end-to-end
+
+Delegation: trust artifacts, not self-reports.
+When verifying delegated work, inspect the actual output artifact (git diff, file contents, runtime behavior), not the delegate's summary. Agents report what they intended, not always what happened.
+
+## 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. A script comparing the old and new compiled output catches what a glance misses.
+
+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 (the **show-me-your-work** skill). Most work just needs it visible, not committed.

package/skills/principle-prove-it-works/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Prove It Works"
+  short_description: "Verify against the real artifact, not a proxy"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-redesign-from-first-principles/README.md

@@ -0,0 +1,16 @@
+# Redesign from first principles
+
+Redesign as if the new requirement had been foundational from day one. Do not bolt it on.
+
+## When it applies
+
+- Integrating a new requirement into an existing design.
+- A change needs to propagate through types, docs, examples, and rationale.
+
+## The rule
+
+Read all affected files and understand the current design holistically. Ask: "if we were writing this from scratch with this requirement, what would we build?" Propagate the change through every reference. Think about the redesign holistically, then deliver it incrementally.
+
+## Related
+
+- [Full rule](SKILL.md)

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

@@ -0,0 +1,16 @@
+---
+name: principle-redesign-from-first-principles
+description: "Apply when integrating a new requirement into an existing design. Redesign as if the requirement had been a foundational assumption from day one, instead of bolting it on."
+disable-model-invocation: true
+---
+
+# Redesign From First Principles
+
+When integrating a change, don't bolt it onto the existing design. Redesign as if the requirement had been there from the start. The result should look like what we would have built if we'd known on day one.
+
+- Read all affected files and understand the current design holistically
+- 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 redesign holistically, then deliver it incrementally
+
+This is the method for preserving option value when integrating changes into an existing design.

package/skills/principle-redesign-from-first-principles/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Redesign from First Principles"
+  short_description: "Redesign as if the new requirement was always there"
+policy:
+  allow_implicit_invocation: false

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

@@ -0,0 +1,16 @@
+# Separate before serializing shared state
+
+When concurrent actors might share mutable state, eliminate the sharing first. Serialize access structurally only when one shared writer is a real invariant.
+
+## When it applies
+
+- Concurrent actors might write the same file, branch, key, or state object.
+- Two workers write their own fields into one shared JSON file.
+
+## The rule
+
+Identify shared mutable state. Default to eliminating the shared write target: give each actor its own file, key, branch, or state directory, and merge only at the read boundary. Only when one shared target is a real invariant, serialize access structurally (lockfiles, sequential phases, single-writer actor, atomic CAS). Instructions and conventions are not concurrency control.
+
+## Related
+
+- [Full rule](SKILL.md)

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

@@ -0,0 +1,16 @@
+---
+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."
+disable-model-invocation: true
+---
+
+# Separate Before Serializing Shared State
+
+When concurrent actors might share mutable state, first ask whether they truly 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.
+
+**Why:** Concurrent writes to shared state create race conditions that are intermittent, hard to reproduce, and expensive to debug. Telling agents or goroutines to "take turns" does not work.
+
+**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/skills/principle-separate-before-serializing-shared-state/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Separate Before Serializing Shared State"
+  short_description: "Eliminate sharing before you serialize writes"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-sequence-verifiable-units/README.md

@@ -0,0 +1,18 @@
+# Sequence verifiable units
+
+Break work into small units that each end in a verifiable state. Check each before the next.
+
+## When it applies
+
+- Multi-step work: sweeps, migrations, runs of similar edits.
+- Deciding how to stack commits and PRs.
+
+## The rule
+
+Each unit is a before/after bracket: known-good state, one change, run the check, proceed. Never batch edits and verify once at the end. Stack commits and PRs so the sequence builds confidence on its own. The canonical shape is the failing test first, then the fix on top, so a reviewer sees both the problem and the proof.
+
+## Related
+
+- [Full rule](SKILL.md)
+- [principle-prove-it-works](../principle-prove-it-works/) (keeps each check real)
+- [principle-build-the-lever](../principle-build-the-lever/) (makes per-unit checks cheap)

package/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."
+disable-model-invocation: true
+---
+
+# 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. The same discipline runs at two altitudes, how you execute and how you deliver.
+
+**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. Never batch the edits and verify once at the end. 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. The first unit shows the bug is real (red), the next shows it resolved (green), so a reviewer sees both the problem and the proof. 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.
+
+**Pattern:**
+- Pick the smallest unit that ends in a check: an edit plus its test, or a commit that stands alone.
+- Verify before advancing. Red to green per unit, never deferred to a final batch.
+- Order the units so the sequence builds confidence on its own, for you while executing and for a reviewer reading the stack.
+
+The sequencing complement to the **prove-it-works** principle skill, which keeps each check real, and the **build-the-lever** principle skill, which makes the per-unit check cheap.

package/skills/principle-sequence-verifiable-units/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Sequence Verifiable Units"
+  short_description: "Break work into small units that each end verified"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-subtract-before-you-add/README.md

@@ -0,0 +1,17 @@
+# Subtract before you add
+
+Remove dead weight first, then build on the simpler base.
+
+## When it applies
+
+- Sequencing an addition, refactor, or rewrite.
+- A stub reference has no novel content.
+- Speculative validators or guards go beyond what the spec demands.
+
+## The rule
+
+Deletion gives you a simpler base, which makes the next addition smaller and less brittle. Sequence removal before construction. Cut before you polish. Design for observed usage, not speculative edge cases. When a reference has no novel content, delete it rather than leaving a stub.
+
+## Related
+
+- [Full rule](SKILL.md)

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

@@ -0,0 +1,22 @@
+---
+name: principle-subtract-before-you-add
+description: "Apply when sequencing an addition, refactor, or rewrite. Remove dead weight, redundant validators, and stub references first, then build on the simpler base."
+disable-model-invocation: true
+---
+
+# Subtract Before You Add
+
+When evolving a system, remove complexity first, then build. Deletion gives you a simpler base, which makes the next addition smaller and less brittle.
+
+**Why:** Adding to a complex system compounds complexity. Removing first cuts the surface area, reveals the essential structure, and usually makes the next design obvious. Default to subtraction.
+
+Make simplification a continual investment. Leave the design slightly simpler and more capable behind the same or smaller surface than you found it.
+
+**The pattern:**
+- 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
+- Out-of-spec features drag validators behind them. Persistence, retry-on-startup, and schema migration each need guards to defend their inputs.
+- Simplify prompts (remove redundant instructions, excessive templates)
+- When a reference has no novel content, delete it rather than leaving a stub

package/skills/principle-subtract-before-you-add/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Subtract Before You Add"
+  short_description: "Remove dead weight first, then build"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-type-system-discipline/README.md

@@ -0,0 +1,19 @@
+# Type system discipline
+
+Use the type checker to eliminate impossible states, mismatched primitives, and unhandled variants at compile time.
+
+## When it applies
+
+- Designing types or a function signature in any typed language.
+- Reviewing code with `as` casts, `any`, or "should never happen" throws.
+- A new variant is added to a sum type.
+
+## The rule
+
+Make illegal states unrepresentable with sum types. Brand semantic primitives so `UserId` and `OrderId` cannot be swapped. Parse external data at boundaries. Do not lie to the type system with casts or unsafe coercions. Exhaust variants so the compiler catches a new case. Derive types from authoritative schemas instead of hand-rolling. Strengthen a type only where partiality appears (runtime assertions, null checks), not for precision's sake.
+
+## Related
+
+- [Full rule](SKILL.md)
+- [typescript-best-practices](../typescript-best-practices/) (TypeScript-specific syntax)
+- [principle-boundary-discipline](../principle-boundary-discipline/)

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

@@ -0,0 +1,31 @@
+---
+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, refuse to lie to the compiler, exhaust variants, derive from authoritative schemas."
+disable-model-invocation: true
+---
+
+# Type System Discipline
+
+The type checker is a proof assistant. Use it to eliminate impossible states, mismatched primitives, and unhandled variants at compile time. A case the types let you ignore becomes a runtime failure the compiler could have stopped. Prefer defining errors and special cases out of existence over proliferating handlers; unrepresentable states, total functions, and interface redesign (the patterns below) are the tools.
+
+Applies to any typed language. Skills like `typescript-best-practices` ground it in specific syntax.
+
+**The patterns:**
+
+- **Make illegal states unrepresentable.** Model variants as sum types: discriminated unions in TypeScript, enums with payloads in Rust/Swift/Kotlin, sealed classes in Scala, ADTs in Haskell/OCaml. Don't model state as a bag of optional fields where contradictory combinations compile. A subtle anti-pattern worth naming: `{ completed: boolean; completedAt?: Date }` admits `completed: true; completedAt: undefined`, which is meaningless. Derive the boolean from a single source like `completedAt !== null`, or model the variants explicitly as `{ kind: 'open' } | { kind: 'done'; at: Date }`. If a bug forces the question "wait, can this combination actually happen?", the type is too loose.
+- **Types are constructions, not restrictions.** Build the type up from the values you want instead of carving them out of a looser type with checks. The invariant that seems to need a refinement type is usually a construction away. A non-empty list is a head plus a rest, not a list with a length check. A valid time range is a start plus a duration, not two timestamps you must keep ordered. No representation is privileged. A list of pairs is an even-length list if you interpret it that way, so choose the shape that cannot build the illegal value and expose the interface callers need on top.
+- **Brand semantic primitives.** `UserId` and `OrderId` are strings underneath but should not be interchangeable. Newtypes in Rust, opaque types in Swift, value classes in Kotlin, phantom types in Haskell, branded intersections in TypeScript. Validate once at creation, trust the type downstream.
+- **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. See the **boundary-discipline** principle skill for where to put validation.
+- **Don't lie to the type system.** Casts, unsafe coercions, and assertion functions that bypass the compiler are runtime crashes waiting to happen. If the compiler can't prove a fact, prove it (validate, narrow, refine the model) or accept that the cast is a hazard. The cast you bury today is the postmortem you write next week.
+- **Exhaustive matching is the compiler's job.** When you match on a sum type, the compiler must fail compilation if a new variant is added without handling. Use the idiom your language provides: `never`-typed binding in TypeScript, unannotated `match` in Rust, `-Wincomplete-patterns` in Haskell, sealed-class match exhaustiveness in Kotlin.
+- **Derive types from authoritative schemas.** When a protocol buffer, OpenAPI spec, GraphQL schema, database migration, or design-system token file defines a shape, derive from it instead of hand-rolling a parallel type. Manual duplication drifts. See the **encode-lessons-in-structure** principle skill.
+- **Strengthen a type only where partiality appears.** A runtime assertion, null check, or "this should never happen" throw marks the place a type is too weak. Push that check up into the type. Then stop. The type system's job is to track the cases each use site must handle, not to describe the data as precisely as possible. Prefer total functions. `sum` of an empty list is 0, so it takes the plain list. `head` of an empty list has no answer, so it demands the non-empty one. Extra precision costs reuse and ceremony and buys no safety.
+
+**The tests:**
+
+- "Can I write a comment explaining when this combination of fields is valid?" If yes, the type is too loose. Split it into a sum type.
+- "Do two of my function arguments share a primitive type but mean different things?" Brand them.
+- "Where did this `any`, this `as`, this `assertNotNull` come from?" Trace it to the boundary and validate there instead.
+- "If a new variant is added next month, will the compiler tell the next agent where to add a case?" If no, the match isn't exhaustive.
+- "Is this type duplicating a shape another file owns?" Derive instead.
+- "Am I strengthening this type to keep an operation total, or just to be more precise?" If nothing would otherwise panic, keep the plain type.

package/skills/principle-type-system-discipline/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Type System Discipline"
+  short_description: "Make illegal states unrepresentable in types"
+policy:
+  allow_implicit_invocation: false

package/skills/recall/README.md

@@ -0,0 +1,23 @@
+# Recall
+
+Reconstruct recent working context from chat history, live state, and the shared record, then return a tight current-state brief.
+
+## When to use
+
+- `/recall`, "recall my work on X", "catch me up"
+- "What have I been working on", "where did I leave off"
+- Before starting or resuming work on a topic
+
+## What it produces
+
+A brief with four sections: a capsule (at most 5 bullets), thread status lines with tags like `[open PR #N]` or `[in flight <branch>]`, recurring problems, and the single most useful next action.
+
+## How it works
+
+Fans out parallel subagents to search the host's transcript store (Claude Code or Codex) for relevant chats. When the topic names a feature, file, or subsystem, also runs the `why` skill's investigators to sweep the shared record (tickets, chat, error tracking). Verifies transcript findings against live git and GitHub state. Writes the brief through the `unslop` skill.
+
+## Related
+
+- [SKILL.md](SKILL.md)
+- [why](../why/) (shared-record investigation)
+- [automate-me](../automate-me/) (turning habits into a skill, not recall)

package/skills/recall/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: recall
+description: "Reconstruct your recent working context from your own chat history, live state, and the shared record (user reports, prior fixes, incidents), then hand back a tight current-state brief. Use for 'recall my work on X', 'catch me up', 'what have I been working on', 'where did I leave off', before starting or resuming work."
+disable-model-invocation: true
+---
+
+# Recall
+
+**Before you start or resume work, you rebuild the user's recent working context and hand back a tight capsule of where things stand now and what to do next.** Use for "recall my work on X", "catch me up", "what have I been working on", or "where did I leave off".
+
+Keep it tight and on-topic. Read only what the in-scope threads need, then stop. The heavy reading fans out to parallel subagents. The main thread keeps only their findings and the final brief.
+
+Your context lives in two records. Your own chat history holds what you did and decided. The shared record holds everything that happened around the same code under other names: the symptoms users keep reporting, the fixes that shipped and got reverted, the errors still firing in prod. That second record is what the **why** skill searches, across source control, the issue tracker, chat and issue channels, long-form docs, and error tracking. A feature with a long bug tail keeps most of its story there, so don't reconstruct it from your transcripts alone.
+
+On Claude Code, transcripts live at `~/.claude/projects/<slug>/<session-uuid>.jsonl`, where `<slug>` is the workspace path with each "/" turned into "-" (so `/Users/you/proj` becomes `-Users-you-proj`). On Codex, session rollouts live under `~/.codex/sessions/<yyyy>/<mm>/<dd>/`. Every line is one chat message.
+
+1. Classify, then route. One specific prior chat to resume is the `session-pickup` playbook, not this. Turning habits into a durable skill is `automate-me`. A human-readable summary of your work is a different task. Recall loads working context across recent chats before you act. If the user already gave you a full state capsule (paths, branch, the change), use it and skip the mining.
+2. Lock the scope before searching. Pin the window ("recent" is a real range, default the last 7 days), the topic if named, and the workspace (default the active one; never read another project's transcripts without being asked). State the scope back. Never quietly turn "all" into "recent N".
+3. Fan out across your chat history. Spawn parallel subagents on a fast, cheap model, each taking a slice of the corpus, since searching transcripts is grunt work. Tell every subagent to order candidates by real modification time (`ls -t`) and never by UUID name, grep the topic first and then read only the matching chats and only their relevant regions, and skip the current chat plus obvious noise (subagent, eval, and test chats). Each returns the same schema, one block per chat: topic, the user's goal, decisions, open threads, struggles and corrections, and artifacts (PRs, tickets, branches), each citing the chat UUID. For one or two chats, skip the fan-out and search directly. The raw transcripts stay in the subagents. The main thread gets only their findings.
+4. Sweep the shared record whenever the topic names a feature, file, subsystem, area, or bug. This is the default, not a judgment call, and "my work on X" does not exempt it. A named target carries history you never see in your own transcripts, and that history is the point of the sweep. Hand it to the **why** skill's source investigators, but steer their question from "why was this built this way" to "what's the current state, what's been tried and didn't hold, and what are users still reporting". Reuse its per-source playbooks so you don't reinvent each query vocabulary, run the investigators in parallel with the chat-history mining, and inherit its posture: one investigator per source, null results are findings, skip an unavailable MCP and say so. Fold what comes back into the brief. Skip this step only for pure activity recall with no named target ("what did I do this week"), where your own history and live state are the entire answer.
+5. Verify against live state. A transcript or a stale ticket is history, not current truth, so take the PRs, branches, and tickets that the mining and the sweep surfaced and check them with `git` and `gh`. When the answer hinges on what an agent actually did (the tools it ran, files it read, errors it hit), read the full transcript, not just a trimmed local copy.
+6. Write the brief to the contract below. Group by thread. Stay on the named topic.
+
+## Output contract
+
+Lead with the capsule, then the thread status, then the problems, then the next move. Deeper detail goes below or gets cut.
+
+- **Capsule.** At most 5 bullets. What this work is and where it stands overall.
+- **Threads.** One line each, prefixed with exactly one status tag: `[merged #N]`, `[open PR #N]`, `[in flight <branch>]`, `[verified, uncommitted]`, `[reverted #N]`, or `[planned, not started]`. A thread with no tag is not done yet, so tag it.
+- **Problems.** At most 5, the recurring ones. Include the symptoms users keep reporting and any fix that shipped and was reverted, so the next attempt starts where the last one failed.
+- **Next move.** The single most useful next action, concrete.
+
+An adjacent feature or ticket stays out unless it blocks this one. When the capsule and thread lines outgrow a screen, cut detail before you cut threads. Write the brief through the **unslop** skill, cite chat findings by UUID and shared-record findings by their source (PR #, ticket ID, chat permalink, error-tracker issue), and sanitize private context before any public output.
+
+**Reply:** the brief, to the contract above.

package/skills/recall/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Recall"
+  short_description: "Reconstruct recent working context from history"
+policy:
+  allow_implicit_invocation: false

package/skills/reflect/README.md

@@ -0,0 +1,24 @@
+# Reflect
+
+Mine the current conversation for durable learnings and route them into concrete skill edits.
+
+## When to use
+
+- `/reflect` or "reflect"
+- After a complex task landed cleanly and the recipe is worth keeping
+- After the agent hit dead ends and found a path that generalizes
+- After the user corrected the agent's approach mid-task
+
+## What it produces
+
+A list of accepted, rejected, and backlog items. Accepted items become skill edits (after user approval). Backlog items file to the team's tracker. The summary names every edit applied, skill created, and item dropped.
+
+## How it works
+
+Locates the active transcript, then spawns three parallel reviewer subagents (judgment, tooling, divergent) on different models. A synthesizer subagent merges findings into accepted, rejected, and backlog lists. A structural enforcement check moves items better served by lint or runtime checks to backlog. Accepted edits require explicit user approval before applying.
+
+## Related
+
+- [SKILL.md](SKILL.md)
+- [references/](references/) (judgment, tooling, divergent reviewer prompts, synthesizer prompt)
+- [principle-encode-lessons-in-structure](../principle-encode-lessons-in-structure/)