rsc-universal 0.1.1

package/skills/parallel/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: parallel
+description: "Use when you have two or more genuinely independent pieces of work and want to fan them out across subagents instead of doing them one after another — disjoint scope, no shared files or state, no ordering dependency, then gather and reconcile the results. Triggers: 'do these in parallel', 'fan this out', 'split this across subagents', 'run these at the same time', 'these tasks are independent, parallelize them', 'dispatch agents for each module', 'hazlo en paralelo', 'reparte esto en subagentes', 'a la vez'. The on-demand SDD helper that implement calls when its task list has disjoint clusters; it owns the partition→dispatch→gather→reconcile discipline. NOT for sequential or data-dependent steps (serialize those), NOT the TDD loop itself (that stays inside implement), NOT git isolation (that's worktrees)."
+tags: [parallel, subagents, fanout]
+recommends: []
+profiles: [core, full]
+origin: risco
+---
+
+# parallel — fan out independent work, then reconcile
+
+*Parallelism is a property of the work, not a wish. Prove the pieces are disjoint, dispatch one subagent per piece with a self-contained brief, then gather and reconcile before anyone calls it done.*
+
+This is an **on-demand process skill** in the SDD chain. You reach it from `implement` (or any phase) when the work in front of you splits into pieces that could each be handed to a different person who never talks to the others. It owns one discipline: **partition → dispatch → gather → reconcile**. It does *not* own the work inside each piece — a subagent building a module still runs its own red → green → refactor loop from `implement`; this skill only orchestrates the fan-out.
+
+The whole value is in the gate at the front. Run work in parallel only when it is *actually* independent. Forcing parallelism onto coupled work does not make it faster — it makes it a merge disaster, and the time you save dispatching you lose tenfold reconciling. Most of this skill is about earning the right to parallelize.
+
+## The independence test (run this before dispatching anything)
+
+A set of tasks is safe to parallelize only when **every** answer below is yes. One no means serialize that pair.
+
+```text
+INDEPENDENCE TEST — for every PAIR of candidate tasks
+- [ ] Disjoint files       — they never write the same file (and don't both edit a shared barrel/index/registry)
+- [ ] No shared state       — no shared in-memory object, DB row, migration, global config, or env they both mutate
+- [ ] No ordering edge      — neither needs the other's OUTPUT to start or to assert against
+- [ ] No hidden coupling     — not the same schema/contract/type that must agree, not the same external resource
+- [ ] Self-containable brief — each can be described fully on its own, with its own done-check, without "see the other task"
+```
+
+If a pair fails any line, they are one serial unit — run them in order in the same agent, or sequence them as a dependency. If a *group* passes for every internal pair, that group is a parallel batch. It is normal to end up with a mix: a few disjoint clusters you fan out, and a serial spine that holds them together.
+
+```text
+Good fan-out  — "add the users repository" ‖ "add the invoices repository" ‖ "write the README"
+                (separate modules, separate files, no task reads another's output)
+Bad fan-out   — "define the User type" ‖ "write the endpoint that returns a User"
+                (the second needs the first's output — serialize: type, THEN endpoint)
+Bad fan-out   — "add field to the orders migration" ‖ "add another field to the orders migration"
+                (same file, same migration — one serial unit, not two)
+```
+
+## The four phases
+
+```text
+PARTITION → DISPATCH → GATHER → RECONCILE
+```
+
+Never skip RECONCILE. Green-in-isolation is not green-together — the point of failure in parallel work is always the seam, and the seam only shows up after you merge.
+
+### 1. PARTITION — carve the work into disjoint units
+
+Take the task list (from `tasks`, or the implicit list in front of you) and group it. For each candidate group, run the independence test above. Produce an explicit partition: the parallel batches and the serial spine between them. Write the partition down — even one line per batch — so the gather step has something to check against. Decide the **degree of parallelism**: one subagent per unit, but cap it where the units would contend on the same scarce resource (a single test database, a rate-limited API, your own review bandwidth). More subagents than you can reconcile is not faster.
+
+### 2. DISPATCH — one subagent per unit, with a self-contained brief
+
+Each subagent gets a brief it can execute **without reading the others**. A brief that says "do the auth part, coordinate with the other agent on the token shape" has already failed the independence test — go back and fix the partition. A complete brief carries:
+
+```text
+SUBAGENT BRIEF (one per unit)
+- Scope        — exactly which files/dirs this unit owns, and the explicit boundary it must NOT cross
+- Goal         — what to build, in its own words, no "see the other task"
+- Done-check   — the verifiable condition that means this unit is finished (from the tasks phase)
+- Constraints  — the constitution rules + stack skill it must honor (e.g. ../fastapi/SKILL.md testing)
+- Selected skills — ids + paths resolved from .rsc/skill-registry.json
+- Compact rules — 4-5 actionable rules digested from those skills for THIS unit
+- Skill fallback — what to do if a referenced skill is unavailable
+- Interface    — any contract it must conform to, FROZEN before dispatch (see the rule below)
+- Report-back  — what to return: the diff, the test output, decisions worth logging, skill_resolution
+```
+
+**Freeze shared contracts before you dispatch, never during.** If two units both touch the same API shape, type, or schema, that interface is a *dependency*, not something to negotiate in flight. Define it in the serial spine first, hand the frozen version to every unit, and only then fan out. Cross-talk between live subagents is the smell that the partition was wrong.
+
+Each subagent still owns its own discipline inside its scope — TDD via `implement`, the stack skill's test mechanics, decision logging. This skill does not relax any of that; it just runs several of them at once.
+
+### Skill resolution feedback
+
+Every subagent result must report:
+
+```yaml
+skill_resolution:
+  used: []
+  missing: []
+  fallback: []
+  compact_rules: []
+```
+
+The orchestrator folds these into the final parallel result. If a unit claims it used a skill that was not available in the registry or not included in the brief, treat that as a review risk and inspect the work before merging.
+
+### 3. GATHER — collect every result, hold the merge
+
+Wait for **all** units to report. Collect each one's diff, test output, and any decisions. Do not start merging the fast ones while slow ones are still running — partial merges create the exact shared-state races you partitioned to avoid. Check each result against its brief's done-check *before* it touches the integration branch: a unit that came back not-actually-done gets sent back, not merged hopefully.
+
+### 4. RECONCILE — merge, then prove the seam holds
+
+This is where parallel work is actually finished. In order:
+
+1. **Merge the units** onto the integration branch (or working tree). Resolve any conflict by hand — a conflict here means the partition leaked (two units touched the same line); note it so the next partition is cleaner.
+2. **Run the *combined* suite.** Each unit was green alone; that proves nothing about together. Run the whole test suite (the stack skill's `scripts/verify.sh`) across the merged result.
+3. **If the combined suite is red**, the failure lives in the seam between units. Switch to `debug` — reproduce → isolate → fix — instead of guessing which unit to blame.
+4. **Reconcile the decision logs.** Fold each unit's decisions into `02-DOCS/wiki/sdd/decisions.md` (append-only), and if two units made a choice that now disagrees, resolve it explicitly and log the resolution.
+
+Only after the combined suite is green is the parallel batch done. Hand the merged, green result back to the phase that called you (usually `implement`, heading for `verify`).
+
+## The accompaniment dial — how loud while fanning out
+
+Read the level from `02-DOCS/wiki/harness/user-profile.md` and match it. The dial changes how much you narrate the orchestration; it never changes the independence test or the reconcile gate.
+
+| Level | While dispatching/reconciling you show… | Questions you ask |
+| --- | --- | --- |
+| **L0** terse | the partition (batches + spine) in one block, then "merged, combined suite green" | none unless a unit fails its done-check or a contract needs freezing |
+| **L1** brief | the partition + one line of *why these are independent* | confirm the partition only where independence is borderline |
+| **L2** decisions | the partition, the frozen contracts, and each reconcile conflict with its fix | confirm before freezing a contract that constrains multiple units |
+| **L3** full | the full independence reasoning per pair, the briefs, the gather, the seam check, narrated | ask to validate the partition before dispatch; teach why the seam is the risk |
+
+L0 still runs the independence test and the combined-suite gate — silently, but completely. Terse is about words, not about skipping the gate.
+
+## When parallel is the wrong tool
+
+Be honest about this — most task lists are *mostly* serial with a few disjoint pockets, not the other way around.
+
+- **The pieces share a file or a contract.** Serialize, or freeze the contract first then fan out the rest. Do not parallelize across a live shared edit.
+- **One piece needs another's output.** That is a dependency edge, by definition sequential. Order them.
+- **There are only two tiny tasks.** Orchestration overhead (writing briefs, gathering, reconciling) can cost more than just doing them in a row. Parallelize when the units are substantial and many, not to look busy.
+- **You can't write a self-contained brief for a unit.** If you cannot describe it without referring to a sibling unit, it is not independent yet. Fix the partition or serialize.
+- **You only need isolation, not concurrency.** Wanting a clean branch/worktree to work in is `worktrees`, not this. This skill is about doing several things *at once*; isolation is about doing one thing *cleanly*.
+
+## Anti-patterns → STOP
+
+| Rationalization | Reality |
+| --- | --- |
+| "These two touch the same file but I'll parallelize and merge later." | Same file = shared state. That's a merge race and lost work. One serial unit. |
+| "I'll let the subagents coordinate the token shape between themselves." | Live cross-talk means the partition failed. Freeze the contract in the spine first, then dispatch. |
+| "Both units are green on their own, so the feature is done." | Green-alone proves nothing about together. Run the combined suite before any done-claim. |
+| "Fan out everything — more subagents is always faster." | Past the point you can reconcile, it's slower and riskier. Cap parallelism at what one serial spine can absorb. |
+| "I'll merge the fast unit now and the slow one when it lands." | Partial merges reintroduce the races you partitioned away. Gather all, then reconcile once. |
+| "It's only two small tasks, but parallel sounds efficient." | Orchestration overhead > the work. Just do them in a row. |
+| "The brief says 'see the other agent's output' — close enough." | That's a dependency, not independence. Serialize, or freeze the output first. |
+| "Combined suite is red, probably the slower unit — I'll tweak it." | Don't guess at the seam. Reproduce and isolate with debug. |
+| "I just want an isolated branch, so I'll use parallel." | That's isolation, not concurrency. Use worktrees. |
+
+## Red flags — stop and re-plan the partition
+
+- A subagent brief can't be written without referencing another unit → not independent; re-partition.
+- Two units both need to edit the same file / migration / barrel / type → collapse them into one serial unit.
+- Subagents are asking to "sync up" mid-run → the contract wasn't frozen; stop, freeze it, re-dispatch.
+- The combined suite is red after merge → the seam leaked; `debug` before continuing, don't checkpoint as done.
+- More open subagents than you can actually review → over-fanned; reduce the degree of parallelism.
+
+## Checklist (copy per fan-out)
+
+```text
+- [ ] PARTITION: independence test passed for every pair; batches + serial spine written down
+- [ ] Shared contracts/types/schemas FROZEN in the serial spine before dispatch
+- [ ] DISPATCH: one self-contained brief per unit (scope, goal, done-check, constraints, report-back)
+- [ ] Each brief includes selected skills, compact rules, and fallback behavior from registry
+- [ ] Each unit honors the constitution + its stack skill; TDD stays inside the unit
+- [ ] GATHER: all units reported; each checked against its done-check BEFORE merge
+- [ ] GATHER: each unit returned skill_resolution (used/missing/fallback/compact_rules)
+- [ ] RECONCILE: merged, conflicts resolved by hand, decision logs folded into 02-DOCS
+- [ ] Combined suite run across the merged result and GREEN (not just green-in-isolation)
+- [ ] Result handed back to the calling phase (usually implement → verify)
+```
+
+## Result envelope
+
+End with:
+
+```json result-envelope
+{
+  "status": "complete",
+  "executive_summary": "Parallel units gathered, reconciled, and combined suite checked.",
+  "artifact": "02-DOCS/wiki/sdd/progress/<slug>.md",
+  "next_recommended": "implement",
+  "risk": "low|medium|high",
+  "skill_resolution": {
+    "used": ["parallel"],
+    "missing": [],
+    "fallback": [],
+    "compact_rules": ["Freeze shared contracts before dispatch.", "Run combined suite after merge."]
+  },
+  "evidence": ["partition", "unit reports", "combined suite output"]
+}
+```
+
+## What this skill is NOT
+
+- **Not the TDD loop.** Each unit's red → green → refactor stays inside `implement`. This skill runs several of those at once; it does not replace the discipline within one.
+- **Not git isolation.** Creating a branch or worktree to work cleanly is `worktrees`. This skill is concurrency across disjoint work, not a clean room for one stream.
+- **Not the task breakdown.** Producing the ordered task list with done-checks is `tasks`; `parallel` consumes that list and decides which pieces can run together.
+- **Not the debugger.** When the combined suite goes red at the seam, switch to `debug` — don't guess which unit to blame.
+
+## Where you are in the chain
+
+`parallel` is on-demand, callable from any phase but most often from `implement`:
+
+`constitution` → `specify` → `clarify` → `plan` → `tasks` → `analyze` → **implement** → `verify` → `review` → `ship`, with `debug` · `worktrees` · **parallel** callable on demand.
+
+**Next:** when the fan-out is reconciled and the combined suite is green, return to the phase that called you — usually `../implement/SKILL.md`, continuing the task list toward `../verify/SKILL.md`. If the seam is red, go to `debug` first. If you discover you actually needed an isolated branch rather than concurrency, that's `worktrees`.

package/skills/parallel/evals/README.md

@@ -0,0 +1,62 @@
+# Eval harness — `parallel` skill
+
+Run by an **agent harness** (an LLM agent with the Skill tool), not a pure shell script.
+`cases.yaml` is the fixture; this README is the honest run procedure. Three things to measure:
+**triggering** (should fire), **anti-triggering** (must not fire), and **capability** (does the
+skill make the fan-out safer and faster).
+
+`parallel` is a process skill — it ships no `scripts/verify.sh`. It is judged on its safety rails
+(the independence test before dispatch, self-contained briefs, frozen contracts, the combined-suite
+reconcile gate), not on a deterministic command.
+
+## 1. Triggering accuracy
+
+For each prompt in `should_trigger` and `should_not_trigger`:
+
+1. Start a fresh agent session with the `parallel` skill available in the catalog, plus its named
+   routing siblings (`implement`, `tasks`, `worktrees`, `debug`) present but not the subject — so
+   routing is realistic.
+2. Feed the prompt verbatim. Do **not** hint that a skill exists.
+3. Observe whether the agent invokes the `parallel` skill.
+4. Run **3–5 trials** per prompt (LLM routing is stochastic); record the fire rate.
+
+Pass conditions:
+- Every `should_trigger` prompt fires `parallel` in **≥ 90%** of trials.
+- Every `should_not_trigger` prompt does **not** fire it in ≥ 90% of trials, and the agent prefers
+  the named `route_to` sibling. The boundaries to watch: `implement` (the serial/TDD work itself,
+  and any ordering-dependent task), `tasks` (makes the list, doesn't fan it out), `worktrees`
+  (isolation, not concurrency), and `debug` (the red post-merge seam). A near-miss leaking into
+  `parallel` — especially parallelizing tasks that share a file or have an ordering edge — is a
+  harder failure than a missed trigger, because it produces a merge race. Fix the description
+  boundary before shipping.
+
+## 2. Capability uplift (with vs without)
+
+For the `capability` scenario:
+
+1. **Without skill:** run the scenario in a clean session, no `parallel` skill loaded. Capture the
+   answer.
+2. **With skill:** run the same prompt with `parallel` (and the named `implement` sibling) loaded.
+3. Grade both against the scenario's `must_include` checklist — one point per bullet that is
+   *concretely* present (e.g. it actually catches that the two migration tasks share a file and
+   collapses them, not just the phrase "check independence").
+4. Use 3 trials each side; average the coverage.
+
+Pass conditions:
+- **With** the skill: `must_include` coverage **≥ 80%**.
+- **Measurable uplift:** with-skill coverage beats without-skill. The expected gaps in the
+  without-skill run are exactly the ones this skill exists to close: blindly parallelizing the two
+  tasks that share the orders migration (the trap), writing briefs that tell subagents to "coordinate"
+  instead of freezing the contract first, merging the fast units before the slow ones land, and
+  declaring done on green-in-isolation without ever running the combined suite.
+
+## What a failing eval tells you
+
+- Trigger misses → the description's "Use when…" triggers are too narrow; widen the phrasings
+  (including the Spanish and the non-obvious "concurrently / at the same time / reconcile" wordings).
+- Near-miss leaks → the boundary against `implement` (serial/dependent work), `worktrees`
+  (isolation), `tasks`, or `debug` is blurry in the description; sharpen the NOT clauses. The most
+  important one to keep tight is the independence boundary — the skill must *refuse* to fan out
+  coupled work.
+- Capability gaps → the SKILL.md body under-specifies the independence test, the contract-freezing
+  rule, the gather hold, or the combined-suite reconcile gate; tighten the relevant section.

package/skills/parallel/evals/cases.yaml

@@ -0,0 +1,44 @@
+skill: parallel
+
+should_trigger:
+  - prompt: "These three modules don't depend on each other at all — the users repo, the invoices repo, and the docs. Fan them out across subagents instead of doing them one by one."
+    why: "Canonical fan-out: multiple disjoint units, no shared state, explicit ask to dispatch concurrently. Squarely this skill's partition→dispatch→gather→reconcile."
+  - prompt: "I've got a bunch of independent tasks in the plan. Split them across agents so they run at the same time, then merge the results."
+    why: "Independent tasks + 'run at the same time' + 'merge the results' is the full fan-out-and-reconcile shape this skill owns."
+  - prompt: "Estas tareas son independientes, no comparten ficheros ni estado. Repártelas en subagentes y hazlas a la vez."
+    why: "Spanish phrasing of the trigger, with the independence preconditions (no shared files/state) named explicitly — this skill's core gate."
+  - prompt: "Dispatch one agent per service to scaffold each one, they're in separate packages and share nothing. Gather what they each produce when they're done."
+    why: "One-subagent-per-unit on disjoint packages plus a gather step — the dispatch and gather phases of this skill, without naming it."
+  - prompt: "Can we parallelize the rest of the build? The auth module and the billing module are in different files and neither reads the other's output."
+    why: "Asks to parallelize while volunteering the independence evidence (different files, no output dependency) — the exact condition this skill checks before fanning out."
+  - prompt: "We have six unrelated cleanup tasks across six different files. Run them concurrently and reconcile at the end so the whole suite still passes."
+    why: "Many disjoint units + concurrency + reconcile-with-combined-suite — non-obvious phrasing that still lands on this skill's reconcile gate (green-together, not green-alone)."
+
+should_not_trigger:
+  - prompt: "First define the User type, then build the endpoint that returns a User. The endpoint needs the type to exist."
+    route_to: "implement"
+    why: "An explicit ordering dependency (second task needs the first's output) — that is a serial unit, handled inside implement, not fanned out. Parallelizing it would fail the independence test."
+  - prompt: "Break this approved plan into an ordered list of small tasks, each with a way to tell when it's done."
+    route_to: "tasks"
+    why: "Producing the ordered task list with done-checks is the tasks phase; parallel consumes that list to decide what can run together, it doesn't create it."
+  - prompt: "I want a clean isolated branch or worktree for this feature so it doesn't touch my current working tree. Set that up."
+    route_to: "worktrees"
+    why: "This is isolation (doing one thing cleanly), not concurrency (doing several at once). Wanting a clean room is worktrees, which parallel explicitly distinguishes itself from."
+  - prompt: "Two of my parallel branches merged and now the combined test suite is red somewhere in the seam. Find the root cause before I change anything."
+    route_to: "debug"
+    why: "Diagnosing a mysterious post-merge failure is the debug protocol (reproduce→isolate→fix); parallel hands the seam off to debug rather than guessing which unit broke."
+  - prompt: "Write each of these tasks test-first — failing test, make it pass, refactor — one commit per task."
+    route_to: "implement"
+    why: "The red→green→refactor TDD loop lives inside implement; parallel runs several such loops at once but never replaces the discipline within a single unit."
+
+capability:
+  - scenario: "User asks: 'I have four tasks left on the plan: (a) add the users repository, (b) add the invoices repository, (c) add a field to the orders migration, (d) add another field to the same orders migration. They feel independent — fan them out across subagents and merge when done.' (FastAPI stack noted in the plan; accompaniment level L2 in the profile.)"
+    must_include:
+      - "Runs the independence test pairwise and correctly identifies that (c) and (d) touch the SAME orders migration/file, so they are NOT independent and must be one serial unit — not two parallel units"
+      - "Partitions into a valid plan: (a) and (b) as disjoint parallel units, (c)+(d) collapsed into a single serial unit, with the partition written down before dispatch"
+      - "Writes one self-contained brief per parallel unit (scope/files owned, goal, done-check, the FastAPI testing constraint, report-back) that does not say 'see the other unit'"
+      - "Freezes any shared contract/type/schema in the serial spine BEFORE dispatching, rather than letting subagents coordinate it live"
+      - "Each unit keeps its own red→green→refactor (delegated to implement + the FastAPI testing reference); parallel does not relax the TDD discipline inside a unit"
+      - "Gathers ALL units, checks each against its done-check before merge, then reconciles: merges, resolves conflicts by hand, folds decision logs into 02-DOCS/wiki/sdd/decisions.md"
+      - "Runs the COMBINED suite across the merged result and refuses to call it done on green-in-isolation; if the seam is red, routes to debug rather than guessing"
+      - "Adapts orchestration verbosity to L2 (shows partition, frozen contracts, and each reconcile conflict with its fix) and hands the green result back to implement → verify"

package/skills/people-ops/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: people-ops
+description: "Use when the offer is signed and you now run the person — building an onboarding plan (preboarding → Day 1 → 30/60/90 ramp), drafting or auditing an internal policy or employee-handbook section (PTO, remote/hybrid, conduct, leave, expenses), standing up the recurring people rhythm (weekly 1:1s, review/goal cycle, headcount), or offboarding a leaver. Triggers: 'build an onboarding plan with a 30/60/90', 'draft a remote-work policy', 'the offer's signed, now what do I need ready before day one?', 'this handbook reads like a contract', 'set up our 1:1 and review cadence', 'someone's leaving — offboarding checklist', 'what HR do we even need?', 'plan de onboarding para el nuevo fichaje', 'redacta la política de teletreball'. NOT sourcing/interviewing/the offer itself (that is hiring)."
+tags: [people-ops, hr, onboarding, employee-handbook, policy, offboarding, one-on-ones, retention]
+recommends: [hiring, contracts, gdpr-privacy, sop-builder, project-ops, e-signature]
+origin: risco
+---
+
+# People-ops
+
+You run the people function as a steady operation, starting the moment a candidate says yes. Three jobs, no more: **onboard** the new hire, **write the policies** that govern them, and **run the people rhythm** so it does not live in one founder's head. The identity line: the offer is signed — now get this person productive, write the policies that bind them, and keep the team's people-rhythm running.
+
+One hard line sits above everything: **you begin at offer-signed.** Sourcing, screening, interviewing, scoring, and the offer itself are not yours — they belong to `../hiring/SKILL.md`. You also do not write the binding instruments. The employment contract, NDA, and IP-assignment are `../contracts/SKILL.md`; the handbook you write explicitly *is not* a contract. Employee-data privacy and GDPR record-handling are `../gdpr-privacy/SKILL.md`. A generic non-people process doc (how we deploy, how we close the books) is `../sop-builder/SKILL.md`; a cross-function team ritual is `../project-ops/SKILL.md`. When the work crosses one of those lines, hand off — do not improvise legal text or a deploy runbook under the banner of "HR."
+
+## The four moments (the spine)
+
+Every request lands in one of four moments. Find the moment first; it tells you the artifact to produce.
+
+| The moment | Trigger | Artifact you produce |
+|---|---|---|
+| **Preboarding** | Offer just signed, start date set | Preboarding checklist — paperwork + access requests pulled *forward* (fact 3) |
+| **Day 1** | Person starts today | Day-1 checklist — access live, equipment ready, intros; **no form marathon** |
+| **Ramp (30/60/90)** | First quarter | A 30/60/90 plan framed learn → contribute → own, with named **manager** moves |
+| **Ongoing rhythm** | Recurring | Weekly 1:1 + review/goal cadence; headcount + who-owns-what |
+| **Exit** | Someone is leaving | Offboarding checklist — same-day access revocation, knowledge handoff, exit conversation |
+
+Do not skip backward. If a founder asks for a 30/60/90 but preboarding never happened, say so — the plan assumes Day 1 already went right.
+
+## Onboarding
+
+The first 90 days decide retention, and almost nobody plans them. ~20% of organizations report half their new hires leave within the first 90 days; only ~29% run a structured 90-day program (Enboarder 2025 HR Leader survey, accessed 2026-06-02). A structured plan is the cheapest retention you will ever buy.
+
+**Pull paperwork into preboarding — protect Day 1.** ~40% of onboarding time is eaten by compliance tasks; e-signature, pre-filled forms, and self-service enrollment cut that from a day to under an hour (Pin / Kayako onboarding guides, accessed 2026-06-02). Send forms, equipment order, and account-provisioning requests in the days *before* the start date. Day 1 is then about people — the team, the manager, the first real task — not a desk of forms. Route the e-signature mechanics to `../e-signature/SKILL.md`.
+
+**The 30/60/90, framed learn → contribute → own:**
+
+- **Days 1–30 — learn.** Tools, codebase/product, who's who, the team's norms. One small shipped thing by day 30 so the win is real, not theoretical.
+- **Days 31–60 — contribute.** Owns a small recurring responsibility; pairs less; gives feedback on a process.
+- **Days 61–90 — own.** Carries a deliverable end-to-end; the ramp is a fact, not a hope.
+
+**Name the manager's moves — this is the biggest lever.** Active manager engagement makes a new hire ~3.4x more likely to report an exceptional onboarding experience, yet only ~18% discuss performance goals with their manager in the first 90 days (Gartner, 3,400 hires, via Asana, accessed 2026-06-02). So the plan must say what the *manager* does, not just HR:
+
+- Day 1: a real welcome and the first concrete task (not "settle in").
+- Week 1: the **goals conversation** — what good looks like at 30/60/90.
+- Assign a **buddy** (peer, not the manager) for the "dumb question" channel.
+- **Weekly 1:1 from week one** — the habit that holds the rest together (see rhythm).
+
+A plan with no named manager and no goals conversation is HR talking to itself. The full preboarding / Day-1 checklists and a 30/60/90 with separate manager and new-hire columns live in `references/templates.md`.
+
+## Day-1 legal clock (US — confirm your jurisdiction)
+
+> **Confirm the jurisdiction before you write a date.** The table below is **US**. The EU, UK, and most countries differ, and many are **not at-will** — do not copy this clock into a non-US plan. Defer the actual employment contract to `../contracts/SKILL.md` and employee-record privacy to `../gdpr-privacy/SKILL.md`.
+
+In the US the Day-1 clock is hard-dated, and the fines are per-form (SHRM / USCIS / E-Verify, accessed 2026-06-02):
+
+| Step | Deadline | Who |
+|---|---|---|
+| I-9 **Section 1** | On or before the first day of work (may be done after acceptance) | Employee |
+| I-9 **Section 2** | Within **3 business days** of hire | Employer |
+| **E-Verify** case (where used) | By the **3rd business day** | Employer |
+
+Paperwork errors run **$288–$2,861 per form** — which is exactly why the I-9 belongs in preboarding for Section 1 and on the calendar for Section 2, not improvised on a busy first morning.
+
+## Writing policy / the employee handbook
+
+A handbook is **"not a contract" only if it says so and avoids contractual language.** Courts treat handbooks as implied contracts when they promise guaranteed employment or rigid progressive discipline (MRA / HRMorning / Mosey, accessed 2026-06-02). Required guardrails on every handbook you draft (US at-will — many countries are not at-will; flag it):
+
+1. An explicit **at-will + "this is not a contract"** disclaimer.
+2. A **signed acknowledgment** the employee returns.
+3. **No mandatory terms** — avoid "will / must / shall guarantee," rigid step-by-step discipline you must follow.
+4. **Re-acknowledge with a version + date** on every material change.
+
+**The minimum-viable handbook is a known short list** (SCORE / Gusto / TalentHR guides, accessed 2026-06-02): equal-opportunity / anti-harassment, attendance + work hours, PTO + sick leave, confidentiality, technology / acceptable use, a disciplinary process, and the signed acknowledgment. Add **remote/hybrid even if you have no remote staff today** — you will.
+
+Every policy uses the same skeleton so they read consistently and have an owner: **purpose → scope → rule → exceptions → owner → effective date.** A policy with no owner and no date is already stale.
+
+**Remote-work framing — privilege, not right, with concrete conditions** (Workable / SHRM, accessed 2026-06-02). State it as a privilege the company can revoke; then make it concrete: a dedicated workspace + confidentiality, company-approved and secured devices, availability during core hours. Conduct rules must address hybrid-specific issues — e.g. personal messaging apps vs corporate tools.
+
+The Bad→Good that decides whether your handbook becomes an accidental contract:
+
+```text
+Bad:  The Company shall guarantee continued employment and shall follow the
+      three-step disciplinary process below before any termination.
+Good: Employment is at-will: either you or the Company may end it at any time,
+      with or without cause or notice. This handbook is a guide, not a
+      contract, and does not promise employment for any period. Where used,
+      progressive discipline is at the Company's discretion and may be
+      skipped. (See your signed acknowledgment.)
+```
+
+"Shall guarantee" and a *mandatory* discipline ladder are the two phrases that hand a plaintiff an implied-contract argument. Full minimum-viable section list with a one-line drafting note each, plus the at-will/acknowledgment boilerplate (carrying its jurisdiction caveat), are in `references/templates.md`.
+
+## The operating rhythm
+
+The people rhythm is layered, and the **weekly 1:1 is the non-negotiable**. Skip the weekly check-in and the quarterly goals quietly collapse back into once-a-year behavior (Peoplebox / WorkBoard / OKR Institute, accessed 2026-06-02).
+
+| Cadence | Frequency | Length | What it is |
+|---|---|---|---|
+| **1:1** | Weekly | 15–30 min | Coaching, not evaluation — blockers, growth, feedback both ways |
+| **Check-in / review** | Monthly or quarterly | 30–45 min | Progress against goals; lightweight written |
+| **Goal cycle** | ~90 days | — | 2 objectives × 3–4 key results per sub-function |
+
+A 1:1 agenda skeleton that keeps it coaching, not status: **wins → blockers → growth → feedback both ways** (you ask for feedback on yourself too — that is what makes the channel real). Let the report own the agenda; you own showing up.
+
+**Offboarding** is the moment most teams botch. Revoke access **same-day** — accounts left live for days are the security hole and the awkward-Slack-message problem. Then: knowledge handoff (what only this person knew, written down before they go), return of equipment, and an honest exit conversation (why they're leaving — the one piece of retention data you can't buy). Full checklist in `references/templates.md`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Fix |
+|---|---|---|
+| Day 1 is a paperwork marathon | Burns the one day that should build belonging; ~40% of onboarding time is compliance | Pull forms + access into preboarding; Day 1 is people + first task |
+| Handbook says "shall guarantee" / mandates a fixed discipline ladder | Hands a plaintiff an implied-contract argument; the handbook stops being "not a contract" | At-will + not-a-contract disclaimer, signed acknowledgment, discretionary discipline |
+| No manager named in the onboarding plan | The 3.4x retention lever goes unused; HR talks to itself | Name the manager's moves: Day-1 task, week-1 goals talk, buddy, weekly 1:1 |
+| Assumes US law everywhere | I-9/E-Verify and at-will are US-specific; most countries are not at-will | Confirm jurisdiction first; flag the clock as US-only; hand the contract to `../contracts/SKILL.md` |
+| Ships a generic SOP and calls it a people policy | A deploy runbook is not a people policy; wrong skeleton, wrong owner | Use purpose→scope→rule→exceptions→owner→date; SOPs go to `../sop-builder/SKILL.md` |
+| Skips weekly 1:1s, relies on the annual review | Quarterly goals collapse into once-a-year behavior | Protect the weekly 1:1; it is the non-negotiable that holds the rhythm |
+| Offboarding leaves access live for days | Security hole + awkward access nobody owns | Revoke access same-day; then handoff, equipment, exit conversation |
+| Writes the employment contract or privacy notice as "HR work" | Crosses into binding legal text / a statutory data regime | Contract → `../contracts/SKILL.md`; employee-data privacy → `../gdpr-privacy/SKILL.md` |
+
+## References
+
+- `references/templates.md` — copy-ready, fill-in material offloaded from the spine: full preboarding / Day-1 / offboarding checklists; a 30/60/90 table with separate manager and new-hire columns; the minimum-viable handbook section list with a one-line drafting note each; the at-will + not-a-contract + acknowledgment boilerplate (with jurisdiction caveat); a 1:1 agenda template; a quarterly review template.

package/skills/people-ops/evals/README.md

@@ -0,0 +1,14 @@
+# people-ops evals
+
+Run these through the repo's eval harness, which feeds each prompt to the skill
+router and grades the result with an LLM. `should_trigger` checks that the listed
+prompts route into `people-ops` (including the non-obvious "the offer's signed,
+now what?" and the Spanish "plan de onboarding ... para el nuevo fichaje" cases);
+`should_not_trigger` checks that adjacent requests route to the named real sibling
+instead (`hiring`, `sop-builder`, `contracts`, `gdpr-privacy`) rather than being
+swallowed here. The single `capability` case is graded against its `must_include`
+rubric — the model must produce an onboarding plan plus a remote-work policy that
+keeps paperwork in preboarding, names the manager's moves, carries the
+at-will/not-a-contract disclaimer, flags the US-only I-9 clock, and defers the
+employment contract to `contracts`. There is no `verify.sh`: this is a
+judgment skill, so its rigor lives in this capability eval, not a script.

package/skills/people-ops/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: people-ops
+
+should_trigger:
+  - prompt: "Our new engineer starts Monday — build me an onboarding plan with a 30/60/90."
+    why: Core onboarding artifact; offer is signed and the ramp plan is the central output.
+  - prompt: "Draft a remote-work policy for our handbook."
+    why: Core policy authoring — a handbook section with the privilege-not-right framing.
+  - prompt: "The offer's signed, what do I actually need to have ready before day one?"
+    why: Non-obvious — no word "onboarding"; this is the preboarding window plus the Day-1 legal clock.
+  - prompt: "Plan de onboarding y un calendario de 1:1s para el nuevo fichaje."
+    why: Spanish; combines onboarding with the operating rhythm (weekly 1:1s).
+  - prompt: "Someone's leaving next week — what's our offboarding checklist?"
+    why: The exit moment — same-day access revocation, knowledge handoff, exit conversation.
+  - prompt: "This employee handbook reads like a contract — can you fix it?"
+    why: Policy audit; the at-will / not-a-contract guardrail is exactly people-ops territory.
+
+should_not_trigger:
+  - prompt: "Write a job description and screen these 40 candidates."
+    route_to: hiring
+    why: Sourcing and screening happen before acceptance; people-ops starts at offer-signed.
+  - prompt: "Document our deployment release process step by step."
+    route_to: sop-builder
+    why: A generic operational procedure, not a people policy.
+  - prompt: "Draft the actual employment contract and NDA for this hire."
+    route_to: contracts
+    why: Legally binding instruments; the handbook people-ops writes explicitly is not a contract.
+  - prompt: "Write our employee-data privacy notice and GDPR record-handling policy."
+    route_to: gdpr-privacy
+    why: A statutory data-protection regime, not an internal HR policy.
+
+capability:
+  - scenario: >
+      A 12-person startup just hired its first non-founder employee, starting Monday.
+      Produce the onboarding plan plus a remote-work policy section for the new handbook.
+    must_include:
+      - A 30/60/90 plan framed learn → contribute → own
+      - Explicit manager actions (Day-1 task, week-1 goals conversation, buddy), not only HR tasks
+      - Paperwork placed in preboarding, not on Day 1
+      - The US I-9 / E-Verify timeline WITH a jurisdiction-confirm flag (this is US; EU/UK differ; many are not at-will)
+      - Remote policy framed "privilege, not a right" with concrete conditions (secured devices, core-hours availability, dedicated workspace)
+      - An at-will + "this is not a contract" disclaimer with a signed acknowledgment
+      - A weekly 1:1 set up from week one
+      - Does NOT write the employment contract itself; defers it to contracts

package/skills/people-ops/references/templates.md

@@ -0,0 +1,129 @@
+# people-ops templates
+
+Copy-ready, fill-in material offloaded from `SKILL.md`. This is lookup/fill-in
+content, not reasoning — adapt the bracketed `[...]` parts. Every legal item
+below assumes **US at-will** unless you change it; confirm your jurisdiction
+before sending (EU/UK and most countries are not at-will).
+
+## Preboarding checklist (days before start)
+
+Paperwork lives here, not on Day 1.
+
+- [ ] Send offer paperwork + employment forms for e-signature (route mechanics to `../e-signature/SKILL.md`)
+- [ ] I-9 Section 1 instructions (employee completes on/before Day 1)
+- [ ] Tax/benefits enrollment via self-service portal
+- [ ] Order equipment (laptop, peripherals, phone) — confirm delivery before start date
+- [ ] Request account provisioning: email, SSO, chat, repos, project tool, calendar
+- [ ] Assign a **buddy** (peer, not the manager); brief them on the role
+- [ ] Manager drafts the first concrete Day-1 task and the 30/60/90 goals
+- [ ] Add the new hire to the team calendar, on-call/rota exclusions, mailing lists
+- [ ] Schedule the recurring **weekly 1:1** starting week one
+- [ ] Welcome note + Day-1 logistics (where/when, dress, lunch plan)
+
+## Day-1 checklist (the person starts)
+
+No form marathon. Access works, equipment is ready, people are introduced.
+
+- [ ] Accounts live and tested (email, SSO, chat, repos) — verify *before* they arrive
+- [ ] Equipment set up; can log in on first try
+- [ ] Manager welcome + the first real task (not "settle in")
+- [ ] Team intros + buddy introduced in person/call
+- [ ] Tour of the docs: where the handbook, the wiki, the on-call live
+- [ ] I-9 Section 1 confirmed complete; calendar I-9 Section 2 (employer, within 3 business days)
+- [ ] E-Verify case if used (by the 3rd business day)
+- [ ] Confirm the week-1 goals conversation is on the calendar
+
+## 30/60/90 plan (manager + new-hire columns)
+
+Framed learn → contribute → own. Fill the bracketed cells per role.
+
+| Window | Theme | New hire does | Manager does |
+|---|---|---|---|
+| Days 1–30 | **Learn** | Tools, product/codebase, team norms; ship one small thing | Day-1 task; week-1 goals talk; weekly 1:1; check buddy is working |
+| Days 31–60 | **Contribute** | Owns a small recurring responsibility; gives process feedback | Stretch the scope; first written check-in; remove blockers |
+| Days 61–90 | **Own** | Carries one deliverable end-to-end | 90-day review; confirm ramp; set next-quarter goals |
+
+Success at 90 days = `[the one deliverable they now own]`.
+
+## Minimum-viable handbook — section list + drafting note
+
+The short list a small company actually needs. One line each.
+
+1. **Equal opportunity / anti-harassment** — state the protected classes and the report channel; name who receives reports.
+2. **Attendance + work hours** — core hours, time-off request flow, expected response norms.
+3. **PTO + sick leave** — accrual or unlimited, how to request, carryover/cap; sick leave per local statute.
+4. **Confidentiality** — what counts as confidential; survives employment; ties to the NDA in `../contracts/SKILL.md`.
+5. **Technology / acceptable use** — approved devices, security baseline, corporate tools vs personal apps.
+6. **Remote / hybrid** — privilege not right; dedicated workspace, secured company devices, core-hours availability.
+7. **Disciplinary process** — describe it as **discretionary**, never a mandatory fixed ladder.
+8. **Acknowledgment** — signed, dated, versioned; re-sign on material change.
+
+## At-will + not-a-contract + acknowledgment boilerplate
+
+> **Jurisdiction caveat:** US at-will only. Most countries are not at-will; in those
+> jurisdictions this language is wrong and may be unenforceable. Have a licensed
+> attorney review before use — you draft and flag, a lawyer signs off
+> (`../contracts/SKILL.md`).
+
+```text
+At-will employment. Your employment with [Company] is at-will. Either you or
+[Company] may end the employment relationship at any time, with or without
+cause and with or without notice. No one other than [the CEO], in a signed
+writing, may change the at-will nature of employment.
+
+Not a contract. This handbook is a guide to current policies and benefits. It
+is not a contract of employment and does not promise employment for any
+specific period. [Company] may add to, change, or withdraw any policy at any
+time, with notice where required by law.
+
+Discipline. Where progressive discipline is described, it is at [Company]'s
+discretion and any step may be skipped. Nothing here requires a fixed sequence
+before termination.
+```
+
+```text
+Acknowledgment (employee signs and returns)
+
+I have received and read the [Company] Employee Handbook, version [X.Y], dated
+[YYYY-MM-DD]. I understand my employment is at-will and that this handbook is
+not a contract. I understand policies may change and that I may be asked to
+re-acknowledge on material changes.
+
+Name: __________________   Signature: __________________   Date: __________
+```
+
+## 1:1 agenda template (weekly, 15–30 min)
+
+Coaching, not status. The report owns the agenda; you own showing up.
+
+```text
+1:1 — [name] — [date]
+1. Wins since last time
+2. Blockers / where you're stuck (manager removes blockers)
+3. Growth — skills, scope, the thing you want next
+4. Feedback both ways — for the report, and ask for feedback on yourself
+5. Action items (owner + date)
+```
+
+## Quarterly review template
+
+```text
+Quarterly review — [name] — [Q# YYYY]
+- Goals this quarter (2 objectives × 3–4 key results): status per KR
+- What went well
+- What to adjust
+- Growth / development focus next quarter
+- Next-quarter goals (set together)
+- Compensation/role notes (if applicable)
+```
+
+## Offboarding checklist (someone is leaving)
+
+- [ ] **Revoke access same-day** — SSO, email, chat, repos, third-party tools, VPN, building badge
+- [ ] Transfer ownership of accounts, files, calendars, on-call, vendor logins
+- [ ] **Knowledge handoff** — what only this person knew, written down before they go
+- [ ] Return equipment; account for company property
+- [ ] Final pay, accrued PTO payout, benefits/COBRA notices per local law
+- [ ] **Exit conversation** — why they're leaving (the retention data you can't buy)
+- [ ] Update headcount + who-owns-what; reassign their responsibilities
+- [ ] Employee-record retention/deletion per `../gdpr-privacy/SKILL.md`