@gcunharodrigues/wrxn 0.7.3 → 0.9.0

package/manifest.json

@@ -298,11 +298,26 @@
       "class": "managed",
       "profile": "project"
     },
+    {
+      "path": ".claude/skills/resolving-merge-conflicts/SKILL.md",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".claude/skills/tdd/SKILL.md",
       "class": "managed",
       "profile": "project"
     },
+    {
+      "path": ".claude/skills/tdd/tests.md",
+      "class": "managed",
+      "profile": "project"
+    },
+    {
+      "path": ".claude/skills/tdd/mocking.md",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".claude/skills/tech-search/SKILL.md",
       "class": "managed",
@@ -343,6 +358,21 @@
       "class": "managed",
       "profile": "project"
     },
+    {
+      "path": ".claude/skills/write-a-skill/GLOSSARY.md",
+      "class": "managed",
+      "profile": "project"
+    },
+    {
+      "path": ".claude/skills/write-an-agent/SKILL.md",
+      "class": "managed",
+      "profile": "project"
+    },
+    {
+      "path": ".claude/skills/write-an-agent/EXAMPLES.md",
+      "class": "managed",
+      "profile": "project"
+    },
     {
       "path": ".claude/skills/audit/SKILL.md",
       "class": "managed",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gcunharodrigues/wrxn",
-  "version": "0.7.3",
+  "version": "0.9.0",
   "description": "WRXN Kernel — installable AI operating system. Two profiles (project | workspace), pull-based updates, managed/seeded/state file classes.",
   "bin": {
     "wrxn": "bin/wrxn.cjs"

package/payload/.claude/skills/diagnose/SKILL.md

@@ -48,9 +48,18 @@ The goal is not a clean repro but a **higher reproduction rate**. Loop the trigg
 
 Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
 
-Do not proceed to Phase 2 until you have a loop you believe in.
+### Completion criterion — a tight loop that goes red
 
-## Phase 2 — Reproduce
+Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** — a script path, a test invocation, a curl — that you have **already run at least once** (paste the invocation and its output), and that is:
+
+- [ ] **Red-capable** — it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring" — it must be able to _catch this specific bug_.
+- [ ] **Deterministic** — same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
+- [ ] **Fast** — seconds, not minutes.
+- [ ] **Agent-runnable** — you can run it unattended; a human in the loop only via `scripts/hitl-loop.template.sh`.
+
+If you catch yourself reading code to build a theory before this command exists, **stop — jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2.
+
+## Phase 2 — Reproduce + minimise
 
 Run the loop. Watch the bug appear.
 
@@ -60,7 +69,15 @@ Confirm:
 - [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
 - [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
 
-Do not proceed until you reproduce the bug.
+### Minimise
+
+Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut — keep only what's load-bearing for the failure.
+
+Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
+
+Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green.
+
+Do not proceed until you have reproduced **and** minimised.
 
 ## Phase 3 — Hypothesise
 

package/payload/.claude/skills/grill-me/SKILL.md

@@ -5,6 +5,6 @@ description: Interview the user relentlessly about a plan or design until reachi
 
 Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
 
-Ask the questions one at a time.
+Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering.
 
 If a question can be answered by exploring the codebase, explore the codebase instead.

package/payload/.claude/skills/handoff/SKILL.md

@@ -2,6 +2,7 @@
 name: handoff
 description: Compact the current conversation into a handoff document for another agent to pick up.
 argument-hint: "What will the next session be used for?"
+disable-model-invocation: true
 ---
 
 Write a handoff document summarising the current conversation so a fresh agent can continue the work.

package/payload/.claude/skills/improve-codebase-architecture/LANGUAGE.md

@@ -51,3 +51,63 @@ What maintainers get from depth. Change, bugs, knowledge, and verification conce
 - **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
 - **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
 - **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.
+
+## Deep vs shallow
+
+**Deep module** — small interface, lots of implementation:
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** — large interface, little implementation (avoid):
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing an interface, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?
+
+## Designing for testability
+
+Good interfaces make testing natural.
+
+**Accept dependencies, don't create them.** A module handed its collaborators can be tested with fakes; one that constructs them internally can't.
+
+```typescript
+// Testable
+function processOrder(order, paymentGateway) {}
+
+// Hard to test
+function processOrder(order) {
+  const gateway = new StripeGateway();
+}
+```
+
+**Return results, don't produce side effects.** A function that returns a value is checked by reading its output; one that mutates state forces the test to rebuild that state first.
+
+```typescript
+// Testable
+function calculateDiscount(cart): Discount {}
+
+// Hard to test
+function applyDiscount(cart): void {
+  cart.total -= discount;
+}
+```
+
+**Small surface area.** Fewer methods = fewer tests needed. Fewer params = simpler test setup.

package/payload/.claude/skills/resolving-merge-conflicts/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: resolving-merge-conflicts
+description: "Use when you need to resolve an in-progress git merge/rebase conflict."
+---
+
+1. **See the current state** of the merge/rebase. Check git history, and the conflicting files.
+
+2. **Find the primary sources** for each conflict. Understand deeply why each change was made, and what the original intent was. Read the commit messages, check the PRs, check original issues/tickets.
+
+3. **Resolve each hunk.** Preserve both intents where possible. Where incompatible, pick the one matching the merge's stated goal and note the trade-off. Do **not** invent new behaviour. Always resolve; never `--abort`.
+
+4. Discover the project's **automated checks** and run them — run the configured test command `$WRXN_TEST_CMD` (falls back to `npm test`), plus any typecheck/format step. Fix anything the merge broke. Use `recon_impact` on the touched symbols to gauge the blast radius of each resolution.
+
+5. **Finish the merge/rebase.** Stage everything and commit. If rebasing, continue the rebase process until all commits are rebased.

package/payload/.claude/skills/tdd/SKILL.md

@@ -18,5 +18,6 @@ verticality review → **tdd** → code review → security review → QA-walk
 ## Rules
 
 - Tests and typecheck pass on **every commit** (Constitution Art. III). A red commit is not done.
-- Test external behavior, not implementation — internals stay refactorable.
+- Test external behavior, not implementation — internals stay refactorable. For test quality see [tests.md](tests.md); for mocking at boundaries see [mocking.md](mocking.md).
 - One slice = one tracer bullet: independently buildable and walkable (Constitution Art. II).
+- **No horizontal slices.** Do NOT write all tests first, then all code — bulk tests pin imagined behavior, not real. One test → one impl → repeat, each cycle learning from the last.

package/payload/.claude/skills/tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/payload/.claude/skills/tdd/tests.md

@@ -0,0 +1,61 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```

package/payload/.claude/skills/to-issues/SKILL.md

@@ -19,6 +19,8 @@ Work from whatever is already in the conversation context. If the user passes an
 
 If you have not already explored the codebase, do so to understand the current state of the code. Issue titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching.
 
+Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change."
+
 ### 3. Draft vertical slices
 
 Break the plan into **tracer bullet** issues. Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer.

package/payload/.claude/skills/to-prd/SKILL.md

@@ -11,7 +11,7 @@ The issue tracker and triage label vocabulary should have been provided to you
 
 1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching.
 
-2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can.
+2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.
 
 Check with the user that these seams match their expectations.
 

package/payload/.claude/skills/triage/OUT-OF-SCOPE.md

@@ -83,7 +83,11 @@ The maintainer may:
 
 ## When to write to `.out-of-scope/`
 
-Only when an **enhancement** (not a bug) is rejected as `wontfix`. The flow:
+Only when an **enhancement** (not a bug) is rejected as `wontfix`.
+
+Do **not** write here when something is closed as `wontfix` because it's **already implemented**. That's a built feature, not a rejected one; recording it would poison the dedup checks with false rejections. Instead, the closing comment points to where the feature already lives.
+
+The flow:
 
 1. Maintainer decides a feature request is out of scope
 2. Check if a matching `.out-of-scope/` file already exists

package/payload/.claude/skills/triage/SKILL.md

@@ -60,7 +60,7 @@ Show counts and a one-line summary per issue. Let the maintainer pick.
 
 ## Triage a specific issue
 
-1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the project's domain glossary, respecting ADRs in the area. Read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue.
+1. **Gather context.** Read the full issue (body, comments, labels, reporter, dates). Parse any prior triage notes so you don't re-ask resolved questions. Explore the codebase using the project's domain glossary, respecting ADRs in the area. Run two checks against the codebase: (a) **redundancy** — search for an existing implementation of the requested behavior by domain concept (not just the request's wording), and report where you looked. If found, it's an already-implemented `wontfix` (step 5). (b) **prior rejection** — read `.out-of-scope/*.md` and surface any prior rejection that resembles this issue.
 
 2. **Recommend.** Tell the maintainer your category and state recommendation with reasoning, plus a brief codebase summary relevant to the issue. Wait for direction.
 
@@ -72,6 +72,7 @@ Show counts and a one-line summary per issue. Let the maintainer pick.
    - `ready-for-agent` — post an agent brief comment ([AGENT-BRIEF.md](AGENT-BRIEF.md)).
    - `ready-for-human` — same structure as an agent brief, but note why it can't be delegated (judgment calls, external access, design decisions, manual testing).
    - `needs-info` — post triage notes (template below).
+   - `wontfix` (already implemented) — the change already exists in the codebase. Point to where it lives; do **not** write to `.out-of-scope/` (that KB is for *rejected* requests, not built ones).
    - `wontfix` (bug) — polite explanation, then close.
    - `wontfix` (enhancement) — write to `.out-of-scope/`, link to it from a comment, then close ([OUT-OF-SCOPE.md](OUT-OF-SCOPE.md)).
    - `needs-triage` — apply the role. Optional comment if there's partial progress.

package/payload/.claude/skills/write-a-skill/GLOSSARY.md

@@ -0,0 +1,181 @@
+# Glossary — Building Great Skills
+
+The domain model for what makes a skill great. A skill exists to wrangle determinism out of a stochastic system; every term below is a lever on that goal. This is the disclosed reference for [`write-a-skill`](SKILL.md).
+
+**Bold terms** in any definition are themselves defined in this glossary; find them by their heading.
+
+## Language
+
+### Predictability
+
+The degree to which a skill makes the agent behave the same *way* on every run — the same process, not the same output (a brainstorming skill should *predictably* diverge; its tokens vary, its behaviour doesn't). The root virtue every other term serves — cost and maintainability are symptoms of it, not rivals.
+
+_Avoid_: consistency, reliability, robustness, output-determinism
+
+### Model-Invoked
+
+A skill that keeps its **description** field, so the agent can see it and fire it autonomously — and the human can still type its name, so model-invocation always *includes* user reach. There is no model-only state: a description only ever *adds* agent discovery, never removes the human's. Pays a permanent **context load** on every turn in exchange for that discoverability. Reachable by other skills, because the description that makes it agent-discoverable makes it invocable. A model-invoked skill whose content is all **reference** is also one home for shared reference: another skill can invoke it, so reference needed by several skills lives in one place. Pick model-invocation only when the agent must reach the skill on its own; if it never fires except by hand, drop the description and pay no context load.
+
+_Avoid_: ability, tool, capability
+
+### User-Invoked
+
+A skill with its **description** stripped — invisible to the agent and reachable only by the human typing its name (user-*only*, where **model-invoked** is user-*and-agent*). Trades agent-discoverability for zero **context load**. Because it has no description, nothing but the human can reach it: no other skill can fire it.
+
+_Avoid_: procedure, workflow, command
+
+### Description
+
+The skill's machine-readable trigger, and the one **context pointer** a **model-invoked** skill is forced to keep loaded at all times. Its mere presence *is* the invocation axis: keep it and the skill is model-invoked (and reachable by other skills); delete it and the skill is **user-invoked**, reachable only by the human. The source of a model-invoked skill's **context load**.
+
+_Avoid_: frontmatter, summary
+
+### Context Pointer
+
+A reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. The **description** is the top-level context pointer (context window → skill); pointers to disclosed files are the same object one level down. Its wording, not the target, decides *when* the agent reaches — and *how reliably*. A must-have target behind a weakly worded pointer is a variance bug: fix the wording first, and inline the material only if sharpening fails.
+
+_Avoid_: link, reference, import
+
+### Context Load
+
+The cost a **model-invoked** skill imposes on the agent's context window — its **description**, always loaded, spending both tokens and attention. What **user-invoked** skills escape by having no description, and the brake on splitting into more model-invoked skills.
+
+_Avoid_: token cost, context bloat
+
+### Cognitive Load
+
+The cost a **user-invoked** skill imposes on the human — what they must hold in their head: which skills exist and when to reach for each (the human is the index). What **model-invocation** removes by being agent-discoverable, and the brake on splitting into more user-invoked skills. Not a cost to minimise: it is the price of human agency, the reason some skills stay user-invoked. Spend it where human judgement matters; remove it where it does not.
+
+_Avoid_: human index, burden, overhead
+
+### Granularity
+
+How finely you divide skills. Finer division spends one of the two loads: more **model-invoked** skills spend **context load** (more descriptions crowding the window and competing for attention); more **user-invoked** skills spend **cognitive load** (more for the human to remember and reach for). Two cuts guide the division. By **invocation**, split off a model-invoked skill where you have a distinct **leading word** to trigger it — a trigger word you actually use in your prompts. By **sequence**, split a run of **steps** where a step's **post-completion steps** need hiding, since isolating it in its own context clears what follows. Beware the reverse: merging sequences exposes each step's post-completion steps to what follows, inviting premature completion.
+
+_Avoid_: chunking, modularity
+
+### Router Skill
+
+A **user-invoked** skill whose job is to point at your other user-invoked skills — naming each and when to reach for it — so the human has one skill to remember instead of many. It can only hint, never fire them: user-invoked skills have no **description**, so nothing but the human can reach them. The cure for **cognitive load** when user-invoked skills multiply.
+
+_Avoid_: dispatcher, menu, registry, index, router procedure
+
+### Information Hierarchy
+
+A skill's content ranked by how immediately the agent needs it — a single ladder, produced by two cuts: in-file or behind a pointer, and step or reference. The rungs:
+
+- **Steps** — in-file, primary
+- **Reference**, in-file — secondary
+- **Reference**, disclosed — behind a **context pointer**
+
+A skill with no **steps** uses just the bottom two rungs — often a legitimately flat peer-set (e.g. every rule of a review on one rung), which is a fine arrangement, not a smell. The hierarchy is independent of invocation: a skill can be model- or user-invoked whether it is all steps, all reference, or both. When a skill has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip — a variance lever, not just a legibility one. Keep the top of the ladder legible; push down it whatever you can.
+
+_Avoid_: structure, organization, layout
+
+### Co-location
+
+Keeping the material an agent needs at once in one place — a concept's definition, rules, and caveats under a single heading, not scattered across the file — so reading one part brings its neighbours with it. The within-file companion to the **Information Hierarchy**: the hierarchy ranks *how far down* a piece sits; co-location decides *what sits beside it* once there. There is no formula for the right format of a body of **reference**; the test is that a skill should read like documentation written for the agent, and grouped material reads that way where scattered material does not. Distinct from **Duplication**: that repeats one meaning in two places, where scattering fragments a single meaning across many.
+
+_Avoid_: grouping, clustering, cohesion
+
+### Branch
+
+A distinct way a skill can be invoked — a case the skill handles — so different runs take different paths through it. A skill with many steps may carry many branches; a linear one has none.
+
+_Avoid_: path, case, fork
+
+### Progressive Disclosure
+
+Moving **reference** down the ladder — out of SKILL.md and behind a **context pointer** — so the top stays legible. Not primarily a token optimisation; it is how the **information hierarchy** is protected. Licensed by **branching**: disclose what only some branches need, inline what every path needs, and if a pointer fires unreliably on must-have material, sharpen its wording, and pull it back inline only if that fails.
+
+_Avoid_: lazy loading, chunking
+
+### Steps
+
+The ordered actions the agent performs — when a skill has them, the primary tier of its content, and the part that earns its place in SKILL.md. Not every skill has steps: a skill can be all steps (`tdd`), all **reference** (a review), or both, independent of invocation. Every step ends on a **completion criterion**, clear or vague.
+
+_Avoid_: workflow, instructions, choreography
+
+### Completion Criterion
+
+The condition that tells the agent a unit of work is done — the target it judges against. Two properties make it a lever, not just a quality. Its **clarity** (can the agent tell done from not-done?) resists **premature completion** — a vague bound ("understanding reached") lets the agent declare done and slip to the next step; this axis needs *steps* to bite, since premature completion is a between-steps failure. Its **demand** (how much it requires) sets **legwork** — "every modified model accounted for" forces thorough work where "produce a change list" does not — and this axis is *not* step-bound: it can bind a body of flat reference too, which is how a skill with no steps still carries an exhaustiveness bar ("every rule applied"). The strongest criteria are both checkable and exhaustive.
+
+_Avoid_: done condition, exit condition, stopping rule
+
+### Post-Completion Steps
+
+The **steps** that follow the current step. Visible, they pull the agent forward into **premature completion** — the more it sees, the stronger the tug; the defence is to hide them by splitting the sequence of steps into two.
+
+_Avoid_: horizon, fog of war, lookahead
+
+### Legwork
+
+The work an agent does behind the scenes within a single step — reading files, exploring the codebase, making changes, digging up what it needs rather than offloading to the user. It lives below the step structure: never written as its own step, latent in the wording, controlled by the agent rather than the skill. The within-step counterpart to **post-completion steps**' across-step pull. Raised by a **leading word** (_comprehensive_, _thorough_) or a **completion criterion** that demands the work be exhaustive — including the demand axis applied to flat reference, which is what drives a skill of flat reference to cover all its rungs. Goes thin either when that demand is missing or when **premature completion** cuts the step short.
+
+_Avoid_: scope, effort, diligence, coverage
+
+### Reference
+
+Material the agent refers to on demand — definitions, facts, parameters, examples, conditional instructions. When a skill has **steps** it is secondary to them; when a skill has none it is the entire content; or it lives outside any skill entirely — see **External Reference**. Reached via **context pointers**, and the prime candidate for **progressive disclosure**.
+
+_Avoid_: supporting material, docs, background
+
+### External Reference
+
+**Reference** that lives outside the skill system — a plain file, no **description**, no **steps**, not invocable — that any skill can point at. The home for shared reference that needn't fire on its own, and the only shared home two **user-invoked** skills can use, since neither has a description and so neither can fire the other.
+
+_Avoid_: doc, resource, knowledge base
+
+### Leading Word
+
+A compact concept — also called a *Leitwort* — already living in the model's pretraining, that the agent thinks with while running the skill. It encodes a behavioural principle in the fewest possible tokens by invoking priors the model already holds (e.g. _lesson_, _proximal zone of development_, _fog of war_, _tracer bullets_). Repeated as a token, never as a sentence, it accumulates a distributed definition across the skill and anchors a whole region of behaviour. Coining your own works if you define it clearly, but a made-up word recruits no priors — you pay in definition tokens what a pretrained word gives free. Reach for an existing word first.
+
+A leading word serves **predictability** twice. In the body it anchors **execution** — the agent reaches for the same behaviour every time the concept appears, and inside flat reference it focuses attention on a class of thing to look for, recruiting the right checks each run. In the **description** it anchors **invocation** — and not only within the skill: when the same word lives in your prompts, your docs, and your codebase, the agent links that shared language to the skill and fires it more reliably. Word a description with the leading words you actually use when you want the skill.
+
+_Avoid_: keyword, term, motif
+
+### Single Source of Truth
+
+The desired state where each meaning lives in exactly one authoritative place, so a change to the skill's behaviour is a change in one place. **Duplication** is its violation.
+
+_Avoid_: home, canonical location
+
+### Relevance
+
+Whether a line still bears on what the skill does — the lens for what to keep. A line loses relevance either by never bearing on the task (mere exposition, or a **branch** that should be disclosed) or by going stale: drifting out of date as the behaviour or world it describes changes. Shorter skills are easier to keep relevant, because each line is cheaper to check. Distinct from **no-op**: relevance asks whether a line bears on the task, not whether it changes behaviour.
+
+_Avoid_: load-bearing, staleness, freshness
+
+## Failure Modes
+
+### Premature Completion
+
+Ending the current step before it is genuinely done, because the agent's attention slips to being done rather than to the work. A between-steps failure: it needs **steps** to occur — a skill with no steps that quits early isn't premature completion but thin **legwork** under an unmet demand. A tug-of-war between two forces: visible **post-completion steps** (the pull forward) and the **completion criterion**'s clarity (the resistance — a sharp, checkable bar holds; a vague one gives way). Fuzziness is the necessary condition: a sharp bound resists the pull no matter how many later steps are visible, so a step that never rushes needs no defending. Two levers hold a step that does, but reach for them in order: **sharpen the bound first** — it is local and cheap. Only when the criterion is irreducibly fuzzy *and* you actually observe the rush do you **hide the later steps** — and hiding only works across a real context boundary (a user-invoked hand-off or a subagent dispatch; an inline model-invoked call leaves the later steps in context and clears nothing). One cause of thin legwork, but distinct from it: legwork can be thin even when a step runs to full completion.
+
+_Avoid_: premature closure, the rush, rushing, shortcutting
+
+### Duplication
+
+The same meaning given more than one **single source of truth**. It costs maintenance (change one place, you must change the others), costs tokens, and inflates prominence — repeating a meaning weights it on the ladder past its real rank. The accidental inverse of a **leading word**, which raises attention on purpose by repeating a token, never the meaning.
+
+_Avoid_: repetition, redundancy
+
+### Sediment
+
+Layers of old content that settle in a skill and are never cleared, because adding feels safe and removing feels risky — so stale and irrelevant lines accumulate and you must core down through them to find what is still live. The default fate of any skill without a pruning discipline; the slow erosion of **relevance**, as opposed to **duplication**'s repeated meaning.
+
+_Avoid_: accretion, bloat, cruft, rot
+
+### Sprawl
+
+A skill that is simply too long — too many lines in SKILL.md — independent of whether they are stale or repeated. Even an all-live, all-unique skill can sprawl. It costs readability (the agent wades through more before it can act, and attention thins across the excess), maintainability (every extra line is one more to keep **relevant**), and tokens. The cure is the **information hierarchy**: push **reference** down behind **context pointers**, and split by **branch** or sequence so each path carries only what it needs. Distinct from **sediment** (length from stale accumulation) and **duplication** (length from repeated meaning) — sprawl is length itself, whatever its cause.
+
+_Avoid_: bloat, length, size, verbosity
+
+### No-Op
+
+An instruction that changes nothing because the model already does it by default — you pay load to tell the agent what it would do anyway. The test: does a line change behaviour versus the default? A line can be perfectly **relevant** and still be a no-op. The same priors that make a **leading word** free make a no-op worthless.
+
+A leading word is a *technique*; No-Op is a *verdict* on a line — and they cross. A leading word too weak to beat the default is a no-op (_be thorough_ when the agent is already thorough-ish), and the fix is a stronger word that passes the verdict (_relentless_), not a different technique. So the No-Op test — does it change behaviour versus the default? — is also how you grade whether a leading word is earning its repetitions. This is model-relative, not reader-relative: two people disagreeing over whether a line is a no-op disagree about the default, and settle it by running the skill, not by debate.
+
+_Avoid_: redundant instruction, restating the obvious, belaboring

package/payload/.claude/skills/write-a-skill/SKILL.md

@@ -1,117 +1,123 @@
 ---
 name: write-a-skill
-description: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.
+description: Author a predictable agent skill — or sharpen an existing one — using the theory that earns predictability: the invocation tradeoff, the information-hierarchy ladder, leading words, completion criteria, and the failure-mode vocabulary. Use when someone wants to create, write, build, or improve a skill, design its structure or progressive disclosure, or says "write a skill", "new skill", or "make a skill".
 ---
 
-# Writing Skills
+# Writing a Skill
 
-## Process
-
-1. **Gather requirements** - ask user about:
-   - What task/domain does the skill cover?
-   - What specific use cases should it handle?
-   - Does it need executable scripts or just instructions?
-   - Any reference materials to include?
-
-2. **Draft the skill** - create:
-   - SKILL.md with concise instructions
-   - Additional reference files if content exceeds 500 lines
-   - Utility scripts if deterministic operations needed
-
-3. **Review with user** - present draft and ask:
-   - Does this cover your use cases?
-   - Anything missing or unclear?
-   - Should any section be more/less detailed?
-
-## Skill Structure
-
-```
-skill-name/
-├── SKILL.md           # Main instructions (required)
-├── REFERENCE.md       # Detailed docs (if needed)
-├── EXAMPLES.md        # Usage examples (if needed)
-└── scripts/           # Utility scripts (if needed)
-    └── helper.js
-```
+A skill exists to **wrangle determinism out of a stochastic system**. **Predictability** — the agent
+taking the same *process* every run, not producing the same output — is the root virtue; every lever
+below serves it. Author skills by reasoning from that virtue, not by filling a template.
 
-## SKILL.md Template
+**Scope:** the theory + a light process for writing skills *well*. For packaging mechanics (the
+`init_skill.py` scaffold, `package_skill.py` validate-and-zip) use **skill-creator**; for a
+separate-context subagent use **write-an-agent**. A skill is a workflow the agent follows inline.
 
-```md
----
-name: skill-name
-description: Brief description of capability. Use when [specific triggers].
----
-
-# Skill Name
+**Bold terms** are defined in **[GLOSSARY.md](GLOSSARY.md)** — the disclosed reference; consult it for
+the full domain model.
 
-## Quick start
+## Invocation — the first decision
 
-[Minimal working example]
+Two choices, trading different costs:
 
-## Workflows
+| | Model-invoked | User-invoked |
+|---|---|---|
+| Reach | agent fires it autonomously + other skills + you by name | only you, by name |
+| Cost | **context load** — the description sits in the window every turn | **cognitive load** — *you* are the index that must remember it |
+| Mechanics | keep `description`, rich trigger phrasing | `disable-model-invocation: true` |
 
-[Step-by-step processes with checklists for complex tasks]
+Pick model-invocation only when the agent (or another skill) must reach it on its own. **wrxn skills
+are model-invoked: never set `disable-model-invocation`.** This skill's own frontmatter is the worked
+example.
 
-## Advanced features
+## The description — the routing lever
 
-[Link to separate files: See [REFERENCE.md](REFERENCE.md)]
-```
+The description is the one **context pointer** a model-invoked skill always keeps loaded, and the only
+thing the agent sees when deciding to load. It does two jobs: state what the skill is, and list the
+**branches** that should trigger it. Every word costs context load, so prune it harder than the body:
 
-## Description Requirements
+- **Front-load the leading word** — the description is where it does its invocation work.
+- **One trigger per branch.** Synonyms renaming a single branch are **duplication** — collapse them.
+- **Cut identity already in the body.** Keep triggers + any "when another skill needs…" reach clause.
+- Third person; end on "Use when [specific triggers]".
 
-The description is **the only thing your agent sees** when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.
+## Information hierarchy — where each piece sits
 
-**Goal**: Give your agent just enough info to know:
+A skill is built from **steps** (ordered actions) and **reference** (definitions, rules, facts), mixed
+freely. Rank every piece on the ladder by how immediately the agent needs it:
 
-1. What capability this skill provides
-2. When/why to trigger it (specific keywords, contexts, file types)
+1. **In-skill step** — an ordered action in SKILL.md. The primary tier: what the agent does, in order.
+2. **In-skill reference** — a rule or fact consulted on demand. Often a legitimately flat peer-set
+   (every rule of a review on one rung) — fine, not a smell.
+3. **Disclosed reference** — pushed into a sibling file (like this skill's GLOSSARY.md), reached by a
+   context pointer, loaded only when it fires.
 
-**Format**:
+**Progressive disclosure** is the move down the ladder so the top stays legible — *licensed by
+branching*: inline what every branch needs, push behind a pointer what only some branches reach. A
+pointer's *wording*, not its target, decides when and how reliably the agent reaches the material.
 
-- Max 1024 chars
-- Write in third person
-- First sentence: what it does
-- Second sentence: "Use when [specific triggers]"
+This ladder — not a line budget — governs what stays in SKILL.md. It retires the old arbitrary rules
+("SKILL.md under 100 lines", "references one level deep"): **sprawl** is the disease, the ladder is the
+cure. Push down whatever you can; keep the top legible.
 
-**Good example**:
+## Completion criteria — defeat premature completion
 
-```
-Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
-```
+Each step ends on a **completion criterion** — the condition that tells the agent the work is done. The
+strongest criteria are both:
 
-**Bad example**:
+- **Checkable** — can the agent tell done from not-done? A vague bound ("understanding reached") invites
+  **premature completion**: the agent declares done and slips to the next step.
+- **Exhaustive** where it matters — "every modified model accounted for", not "produce a change list".
+  The demand drives thorough **legwork**, and binds flat reference too ("every rule applied").
 
-```
-Helps with documents.
-```
+Sharpening the bound is the cheapest defence against a rushed step — reach for it before any structural
+fix.
 
-The bad example gives your agent no way to distinguish this from other document skills.
+## Leading words — anchor behaviour in one token
 
-## When to Add Scripts
+A **leading word** (*Leitwort*) is a compact concept already living in the model's pretraining that the
+agent thinks with while running the skill (*lesson*, *fog of war*, *tracer bullets*, *red*/*green*).
+Repeated as a token — not as a sentence — it accumulates a distributed definition and anchors a whole
+region of behaviour in the fewest tokens, by recruiting priors the model already holds. It serves
+predictability twice: in the body it anchors *execution*; in the description it anchors *invocation*
+(shared language across your prompts, docs, and code makes the agent fire the skill more reliably).
 
-Add utility scripts when:
+Hunt restatements a leading word retires — "fast, deterministic, low-overhead" → *tight*; "a loop you
+believe in" → *red*. Reach for an existing pretrained word first; a coined word recruits no priors, so
+you pay in definition tokens what a pretrained word gives free.
 
-- Operation is deterministic (validation, formatting)
-- Same code would be generated repeatedly
-- Errors need explicit handling
+## Prune — and the failure modes it prevents
 
-Scripts save tokens and improve reliability vs generated code.
+- **Single source of truth** — each meaning in exactly one place, so a change is a one-place edit.
+- **Relevance** — does each line still bear on what the skill does? Cut stale lines.
+- **No-op test** — does a line change behaviour versus the model's default? Hunt no-ops sentence by
+  sentence; when one fails, delete the whole sentence, don't trim words. Be aggressive. A weak leading
+  word (*be thorough* when the agent already is) is a no-op — fix with a stronger word (*relentless*).
 
-## When to Split Files
+Use this vocabulary to diagnose a misbehaving skill:
 
-Split into separate files when:
+| Mode | What it is | Cure |
+|---|---|---|
+| **Premature completion** | a step ends before it's done; attention slips to *being done* | sharpen the criterion first; only then split to hide post-completion steps |
+| **Duplication** | one meaning in two places | collapse to a single source of truth |
+| **Sediment** | stale layers that settle because adding feels safe, removing risky | a pruning discipline (relevance) |
+| **Sprawl** | simply too long, even when every line is live and unique | the ladder — disclose reference, split by branch |
+| **No-op** | a line the model already obeys by default | delete it, or strengthen a weak leading word |
 
-- SKILL.md exceeds 100 lines
-- Content has distinct domains (finance vs sales schemas)
-- Advanced features are rarely needed
-
-## Review Checklist
-
-After drafting, verify:
+## Process
 
-- [ ] Description includes triggers ("Use when...")
-- [ ] SKILL.md under 100 lines
-- [ ] No time-sensitive info
-- [ ] Consistent terminology
-- [ ] Concrete examples included
-- [ ] References one level deep
+1. **Gather** — the task/domain, the concrete use cases (the **branches**), executable scripts vs just
+   instructions, reference material to bundle. Ask only the few that matter; don't overwhelm.
+2. **Draft** — write the `description` first (it's the routing lever); body in **imperative form**
+   (verb-first, not second person); rank every piece on the ladder; disclose reference behind pointers.
+3. **Prune + review** — run the no-op test; check single source of truth + relevance; present to the
+   user (covers the cases? missing? right altitude?).
+
+## Validate
+
+- [ ] Frontmatter `---` opens/closes; `name` present, kebab-case, equals the folder.
+- [ ] `description` is third person, states what + "Use when…" triggers, front-loads the leading word.
+- [ ] **No** `disable-model-invocation` (wrxn skills are model-invoked).
+- [ ] Every step ends on a checkable — and where it matters, exhaustive — completion criterion.
+- [ ] Reference only some branches need is disclosed behind a pointer, not buried inline.
+- [ ] No duplication / sediment / sprawl / no-ops; leading words used consistently throughout.

package/payload/.claude/skills/write-an-agent/EXAMPLES.md

@@ -0,0 +1,38 @@
+# write-an-agent — Examples
+
+## A compressed read-only locator
+
+A canonical interactive subagent: a single job, a least-privilege grant (read-only — no `Bash`, so no
+push path), `haiku` (the work is mechanical), and a tight output contract with a concrete example.
+
+```
+---
+name: route-finder
+description: >
+  Read-only locator for HTTP routes. Returns a path:line table of where each route
+  is defined and its handler. Use PROACTIVELY when someone asks "where is the X
+  route", "what handles the Y endpoint", or "list all routes".
+tools: Read, Grep, Glob
+model: haiku
+---
+You locate HTTP routes and report them. Nothing else.
+
+## Process
+1. Grep for route definitions (router calls, decorators, path strings).
+2. Resolve each route's handler symbol.
+3. Emit the table. Stop.
+
+## Constraints
+- Read-only — never edit, run git, or propose changes.
+- No preamble, no prose padding.
+
+## Output
+Your final message IS the result. One row per route, nothing else:
+`METHOD /path — handler@file:line`
+Example:
+`GET /users — listUsers@api/users.ts:42`
+```
+
+**Why it's SOTA:** read-only grant (no push path), `haiku` (mechanical), the `description` leads
+delegation with "use PROACTIVELY" + exact trigger phrases, and the output contract is a fixed
+one-row-per-route shape — the caller gets a compact table, not prose.

package/payload/.claude/skills/write-an-agent/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: write-an-agent
+description: Create a state-of-the-art interactive Claude Code subagent (.claude/agents/<name>.md) through a guided interview — pin its single job, routing trigger, least-privilege tools (you approve the grant), model, and a mandatory compressed output contract, then scaffold and validate the subagent file. Use when someone wants to create, add, or scaffold a subagent, build a custom agent, or says "write an agent", "create an agent", or "new subagent".
+---
+
+# Writing an Agent
+
+Scaffold an **interactive subagent** — a `.claude/agents/<name>.md` file spawned via the Agent/Task
+tool — through a short interview that gets the few SOTA levers right. Your job here is not to fill a
+template; it is to **interrogate the job until the subagent is sharp, cheap, and safe**, then write a
+validated file.
+
+**Scope:** interactive helpers (locators, reviewers, runners you call in-session). **Not** AFK
+pipeline executors — those live in the kernel's dispatch-executor registry (`wrxn dispatch`). If the
+user wants a workflow *they* follow inline, write a skill instead (`write-a-skill`).
+
+## Why a subagent (the levers that make it good)
+
+A subagent is a **separate context** with its own tools, model, and system prompt. The caller sees
+**only its final message**. That one fact drives every lever:
+
+| Lever | Why |
+|---|---|
+| **Single responsibility** | One narrow job → sharp prompt → correct routing. An "and" means two subagents. |
+| **`description` = #1 routing lever** | The main thread matches this text to delegate. Vague → mis-routed. Use "use PROACTIVELY" + trigger phrases. |
+| **Least-privilege `tools`** | Omitting `tools` inherits ALL tools. Smaller surface = safer + cheaper. |
+| **Compressed output contract** | The caller eats only the final message. A terse fixed shape is the highest-value, most-skipped lever. |
+| **Stateless** | No memory but the spawn prompt + this file. Put everything it needs on the page. |
+| **Model match** | Mechanical → haiku; reasoning → sonnet; hard → opus. |
+
+## File format (verified — code.claude.com/docs sub-agents)
+
+```
+---
+name: <kebab-case, equals the filename>
+description: >
+  <what it does> + WHEN. Include "use PROACTIVELY" + trigger phrases.
+tools: Read, Grep, Glob          # explicit allowlist ALWAYS — omitting inherits ALL tools
+model: haiku                      # haiku | sonnet | opus | inherit
+skills: tdd                       # OPTIONAL — preloads that skill's content at startup
+---
+<system prompt — SOTA body order below>
+```
+
+Real fields: `name`, `description`, `tools`, `model`, `skills` (advanced: `disallowedTools`,
+`permissionMode`). Don't invent others.
+
+## Interview — run in this order
+
+1. **Job** — the ONE responsibility. If it needs an "and", STOP and propose two subagents.
+2. **Trigger** — when should the main thread delegate? → becomes `description`:
+   `<what it does>. Use PROACTIVELY when <the exact situations/phrases that route to it>.`
+3. **Propose frontmatter → ONE consolidated approval.** Infer from the job, then show `tools` +
+   `model` + `skills` together as a single preview; the operator approves or edits before you continue:
+   - **tools** — the minimal allowlist. Locator/reviewer → `Read, Grep, Glob`; + run things → `+Bash`;
+     mutates files → `+Edit, Write`; research → `WebFetch, WebSearch`; integration →
+     `mcp__<server>__<tool>` (named, never `*`). **Never omit** (= inherit-all). **Never grant a push
+     path** (no devops). Flag `Bash` as broad (reaches `git` + the network).
+   - **model** — mechanical → `haiku`, reasoning → `sonnet`, hard → `opus`, match the caller → `inherit`.
+   - **skills** — propose only if the job maps to a skill **installed here** (`.claude/skills/<name>/`
+     exists; a dangling preload = a broken subagent). Don't auto-add `caveman` — compression ships via
+     the body instruction, which is portable.
+4. **Output contract (mandatory)** — pin exactly what returns + how terse: a fixed return shape (e.g.
+   `path:line — finding`, one per line; or small JSON) **and** a compression instruction (lead with the
+   answer, drop prose, backtick exact paths/symbols). Don't finish the subagent without it.
+5. **Generate → validate → write** (below).
+
+## Body structure (SOTA order — every subagent)
+
+1. **Role** — one line: who it is + the single job.
+2. **Process** — the numbered steps it follows.
+3. **Constraints** — hard NOs: what it refuses (scope creep; edits if read-only; ever pushing).
+4. **Output contract** — the fixed return shape + **one concrete example**. State plainly: *your final
+   message IS the return value — return the result, not a conversational reply.* Compress.
+5. **Stateless reminder** — it gets only its spawn prompt + this file; no main-thread memory, no
+   inherited CLAUDE.md persona. Keep the page self-sufficient.
+
+## Validate (loose by design)
+
+- [ ] `---` fences open/close; `name` present, kebab-case, equals the filename.
+- [ ] `description` says **what** + **when** (the routing trigger; uses "use PROACTIVELY").
+- [ ] `tools` is an explicit allowlist of **real** tools; present, never omitted; no push path.
+- [ ] `model` ∈ `haiku | sonnet | opus | inherit`.
+- [ ] `skills` (if present) names a skill that exists under `.claude/skills/`.
+- [ ] Body has Role + Process + Constraints + Output contract (with an example).
+- Don't hard-gate `tools` against a frozen list — new MCP tools are valid.
+
+## Write + load
+
+- Write `.claude/agents/<name>.md` at the install root. **Brownfield-safe**: if it exists, STOP —
+  offer to edit or rename, never overwrite.
+- **Loading:** a file written to disk is **not live this session**. Tell the operator to **restart
+  Claude Code, or create/refresh it via the `/agents` interface** (which loads immediately). Then it is
+  invokable by the Agent/Task tool, a workflow, or FleetView.
+
+See **[EXAMPLES.md](EXAMPLES.md)** for a complete worked subagent.