geneseed 2.0.0

package/src/skills/drill.md

@@ -0,0 +1,28 @@
+# {{SKILL}}: drill
+
+> {{DESC_DRILL}}
+
+**Trigger:** the user wants to *practise* a concept until it is reflex rather than have it explained — "drill me on X", "quiz me until it sticks", "don't explain it, make me use it". For a from-zero overview use [crash-course](crash-course.md); for making confusing material click in the first place use [decode](decode.md).
+
+## Procedure
+1. Pin the concept and confirm the user wants to be tested, not lectured. Do not explain the concept up front.
+2. Drop them straight into a realistic situation where they would have to use it and would probably make a mistake.
+3. When they make a mistake, withhold the answer. Instead ask the one question that forces them to find where their own reasoning broke.
+4. Reveal the answer only after they have made at least two honest attempts.
+5. Repeat the cycle — new situation each time — until they get it right without hesitation. Then name the variation most likely to catch them out next.
+
+## Done when
+- The user works through the situation correctly without hesitation and without being handed the answer.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/feynman.md

@@ -0,0 +1,26 @@
+# {{SKILL}}: feynman
+
+> {{DESC_FEYNMAN}}
+
+**Trigger:** the user just studied something and wants to find out whether it actually stuck by explaining it back — "let me explain X to you", "check my understanding of X", "I just learned X, did it land?". For routing toward a goal use [learning-path](learning-path.md); for stress-testing a mastery the user already claims, use [gap-detector](gap-detector.md).
+
+## Procedure
+1. Have the user explain what they studied as if teaching a ten-year-old.
+2. Interrupt the moment they (a) use jargon they cannot themselves unpack, (b) skip a step in the reasoning, or (c) simplify so far that the explanation becomes wrong. Name which of the three it was each time, and keep them going.
+3. At the end, tell them exactly what those stumbles reveal about what is not yet solid in their understanding, and what to restudy — directly, no flattery.
+
+## Done when
+- The user explained the topic through to the end, every jargon/gap/over-simplification was caught and labelled in the moment, and the run ends with a concrete readout of what isn't solid and what to restudy.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/forge-mcp.md

@@ -0,0 +1,48 @@
+# {{SKILL}}: forge-mcp
+
+> {{DESC_MCP}}
+
+**Trigger:** building, extending, or hardening a Model Context Protocol (MCP)
+server — exposing an external API or service to an agent as a set of tools.
+
+**Requires:** Node.js/`npx` to run the MCP Inspector — the verification in steps 5–6
+depends on it.
+
+## Procedure
+1. Research first ({{LAW}} XVII): read the MCP specification
+   (`modelcontextprotocol.io`) and the target service's API docs, then pick the
+   SDK — Python (FastMCP) or TypeScript (MCP SDK) — and load its documentation.
+2. Plan the tool surface: list the service's key operations and design
+   action-oriented, prefixed tool names. Prefer a few task-shaped tools over one
+   thin wrapper per endpoint — a tool is judged by whether an LLM can complete a
+   real task with it.
+3. Build the core: an authenticated API client, shared error-handling and
+   pagination helpers, and response formatting that returns focused, relevant
+   data rather than raw dumps ({{LAW}} XV).
+4. Define each tool's input and output schema (Pydantic or Zod), set the
+   annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`,
+   `openWorldHint`), and write error messages that name the specific, actionable
+   fix.
+5. Review and test: kill duplication, ensure consistent errors and full type
+   coverage, then build and exercise every tool with the MCP Inspector — don't
+   assume it works ({{LAW}} III).
+6. Evaluate: pick ~10 realistic, read-only questions that each need multiple tool
+   calls and have one verifiable, stable answer; run them and confirm the server
+   actually answers them.
+
+## Done when
+- The server builds, every tool passes the Inspector, and the evaluation
+  questions are answered correctly through the tools — not by guesswork.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/fresh-eyes.md

@@ -0,0 +1,29 @@
+# {{SKILL}}: fresh-eyes
+
+> {{DESC_FRESH_EYES}}
+
+**Trigger:** a task is claimed done and the solving session believes the artifact works — before merge or handoff, or when the user asks to "validate", "fresh eyes", "prove it meets the spec", "did this actually solve it", or "independent sign-off", and the cost of a confidently-wrong "done" is high. This re-judges the *result* from zero context — distinct from [geneseed-code-review](geneseed-code-review.md), which reviews a *diff* with full knowledge of the change. For an open-ended quality critique use [roast-me](roast-me.md); for a multi-stance debate over an undecided question use [council](council.md).
+
+## Procedure
+1. Capture the firewall input as TWO things and nothing else: (a) the **verbatim original task/spec** — the raw issue or request text, NOT a solver-written summary or "spec card" (a distilled card launders the solving session's framing into the rubric, the very bias this {{SKILL}} exists to defeat), and (b) a pointer to the **final artifact** as it stands — file paths, built output, or the command to run it. If the raw task is too thin to yield acceptance criteria, have the **user** (never the solver) confirm a one-line acceptance bar, then proceed ({{LAW}} III); if it is too fuzzy even for that, this is a judgement call — convene [council](council.md) instead.
+2. Deliberately WITHHOLD everything else and say so in the brief: the diff and changed-files list, the chat transcript, the solver's rationale and commit messages, prior test output, and every "it works because…" claim. Each is a vector for confirmation bias — they transmit the author's conviction, and a validator that inherits it cannot judge independently ({{LAW}} VIII). The validator must re-confront the artifact cold, the way an external recipient would.
+3. Dispatch ONE fresh-context validator whose context starts empty — isolation is structural, not promised — using the [reviewer {{AGENT}}](../{{DIR_AGENTS}}/reviewer.md) (read-only, runs the suite, casts a verdict; NOT the [skeptic](../{{DIR_AGENTS}}/skeptic.md), whose charter forbids running commands and casting verdicts), via the dispatch pattern in [parallel-agents {{SKILL}}](parallel-agents.md), keeping the heavy reading out of the main context ({{LAW}} XV); a cheaper model suffices for the validator unless the spec is subtle. Dispatch **fresh** — never resume a prior subagent session, which re-inherits its context and breaches the firewall. Where the host has no subagent capability, degrade: write the brief to a file and have the user run it in a separate fresh process; only as a last resort run the persona in-session and **stamp the verdict "SOFT ISOLATION — context bleed possible"** so the user discounts it. Never silently pretend a persona equals a fresh agent.
+4. Inside the fresh context, FIRST derive the rubric blind: from the task ALONE — before looking at the artifact — write a numbered list of observable acceptance criteria, each a yes/no test with a stated check method (a command to run, an output to see, a behaviour to exercise), tagged must-have or nice-to-have. FREEZE this list. Deriving it inside the firewall, from the task and not the solution, is what prevents criteria-fitting — the rubric cannot be bent to match what the artifact happens to do.
+5. THEN reveal the artifact and rule each criterion against it under an inverted burden of proof: actively check it — run the command, exercise the behaviour, read the named output ({{LAW}} III — verify by running, never assume) — and record `Cn: PASS | FAIL | UNVERIFIABLE — <evidence: the exact output/behaviour checked>`. Default is NOT-PASS: mark PASS only after actively confirming; a criterion that cannot be checked is UNVERIFIABLE (a finding, not a pass — name the missing evidence). Flag any **Extra** the artifact added beyond the spec, but cut gold-plating both ways — never FAIL the artifact for a requirement the task never asked for. The validator does NOT fix, refactor, or polish; it only rules.
+6. Return the independent verdict: the per-criterion table, then the overall gate — **SATISFIES** (every must-have PASS, no FAIL), **SATISFIES-WITH-GAPS** (must-haves pass, a nice-to-have fails), or **DOES-NOT-SATISFY** (any must-have FAIL or UNVERIFIABLE), listing the failing criteria with evidence. Report "could not find a fault" as not-proven-false, never as "proven correct". Surface it for the user to decide; the gate advises and applies no changes — write no code, push nothing ({{LAW}} IV, {{LAW}} XX). On DOES-NOT-SATISFY, hand the failures to the solver (optionally via [review-response](review-response.md)) and re-run fresh-eyes after the fix rather than letting the original context relitigate the ruling.
+
+## Done when
+- A fresh context that never saw the solving session derived the acceptance criteria from the original task alone, froze them before seeing the artifact, ruled each PASS/FAIL/UNVERIFIABLE with evidence by checking the live artifact, and returned an overall gate (SATISFIES / SATISFIES-WITH-GAPS / DOES-NOT-SATISFY) for the user to weigh — or, where no true isolation was possible, the verdict is stamped soft-isolation so it is discounted.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/frontend-design.md

@@ -0,0 +1,58 @@
+# {{SKILL}}: frontend-design
+
+> {{DESC_FRONTEND_DESIGN}}
+
+**Trigger:** building a new UI or reshaping an existing one, and it should carry a
+deliberate point of view rather than read as a templated default.
+
+**Requires:** a way to render and screenshot the result (a browser or the host's
+preview tool) — the second-pass critique in step 6 cannot run without one.
+
+## Procedure
+1. Ground it first: name the concrete subject, the audience, and the single job
+   this page does. Draw distinctive choices from the subject's own world — its
+   materials, instruments, artifacts, and vernacular — and build with real
+   content, not lorem.
+2. First pass — write a compact design plan before any code:
+   - **Color:** 4–6 named hex values, each with a description.
+   - **Type:** a characterful display face used sparingly, a complementary body
+     face, and a utility face for captions/data if needed — paired deliberately,
+     not your default reach.
+   - **Layout:** one-sentence prose plus an ASCII wireframe per section.
+   - **Signature:** the single element that embodies this brief.
+3. Open with the hero as thesis: the most characteristic thing in the subject's
+   world (headline, image, animation, live demo), not a templated big-number row.
+4. Make structure earn its place — numbered markers (01/02/03) only for genuine
+   sequences; cut any device that decorates without encoding information. Deploy
+   motion only where it serves the subject; scattered animation reads as
+   AI-generated.
+5. Avoid the three tells unless the brief truly calls for them: (a) cream
+   `#F4F1EA` + high-contrast serif + terracotta accent; (b) near-black + acid-green
+   or vermilion accent; (c) broadsheet hairline rules, zero radius, dense columns.
+6. Second pass — critique against the brief ({{LAW}} III): screenshot the result
+   and read it. If any part reads like the generic default you'd produce for any
+   similar page, revise it. Spend boldness in one place and keep the rest quiet;
+   remove one accessory. Hold the quality floor without announcing it — responsive,
+   visible keyboard focus, reduced-motion support.
+7. Treat UI copy as design material, not decoration: end-user's viewpoint, active
+   voice, one name per action through the whole flow ("Publish" → "Published").
+   Errors explain the fix; empty states invite action. Run the
+   [prose {{SKILL}}](../{{DIR_SKILLS}}/prose.md) over the words.
+
+## Done when
+- The design makes one justified aesthetic risk specific to this brief, carries no
+  templated tells, holds the accessibility floor, and a screenshot critique finds
+  nothing that reads as a generic default.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/gap-detector.md

@@ -0,0 +1,27 @@
+# {{SKILL}}: gap-detector
+
+> {{DESC_GAP_DETECTOR}}
+
+**Trigger:** the user believes they already master a skill or topic and wants that belief stress-tested — "I think I already know X, prove me wrong", "test whether I really understand X", "find the holes in what I know". For routing toward a goal use [learning-path](learning-path.md); for checking freshly-studied material use [feynman](feynman.md).
+
+## Procedure
+1. Take the skill the user claims to master. Set the contract plainly: you will try to prove them wrong, and you will not go easy.
+2. Ask five questions that look simple but separate someone who has truly gone deep from someone who has only skimmed — edge cases, "why", the assumption under the rule, the case where the standard answer breaks.
+3. For every answer the user gives, say plainly what it reveals about what is still missing in their foundation. If an answer is shallow, name it as shallow and say what depth would have looked like — no flattery.
+4. Close with the honest verdict: the specific gaps to fill before the mastery claim holds.
+
+## Done when
+- All five questions were asked, each answer was met with a direct read of what it exposes, and the run ends with a concrete verdict on the remaining gaps — never empty praise.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/geneseed-code-review.md

@@ -0,0 +1,33 @@
+# {{SKILL}}: geneseed-code-review
+
+> {{DESC_CODE_REVIEW}}
+
+**Trigger:** reviewing changes before merge, or the user asks for a review.
+
+## Procedure
+1. Read the task/issue the change is meant to satisfy.
+2. Get the diff. For a large change, consider dispatching the
+   [reviewer {{AGENT}}](../{{DIR_AGENTS}}/reviewer.md) to keep the main context clean.
+3. Pass 1 — correctness: logic errors, edge cases, error handling, race
+   conditions. Verify suspect behaviour by running tests, not by assuming.
+4. Pass 2 — quality: duplication, naming, dead code, units that do too much.
+5. Pass 3 — spec fidelity: compare the diff against the task or issue from
+   step 1; flag anything asked for but missing, and anything present that was
+   never asked for. No spec available → say so and skip the pass.
+6. Write each finding as `file:line — problem — fix`, correctness first.
+
+## Done when
+- Findings are reported with a clear verdict: ship / fix-then-ship / block.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/geneseed.md

@@ -0,0 +1,29 @@
+# {{SKILL}}: geneseed
+
+> {{DESC_GENESEED}}
+
+**Trigger:** the user mentions Geneseed, the harness, `AGENT.md`, or asks you to inspect, read from, or refresh the deployed bundle — or you need to know what {{LAWS}}, {{AGENTS}}, or {{SKILLS}} are available in the current install.
+
+## Procedure
+1. Locate the deployment. Try in order: `command -v geneseed` (use the launcher if found); `$GENESEED_HARNESS`; `$OPENCODE_CONFIG_DIR`; `~/.config/opencode/AGENT.md`; `.opencode/AGENT.md` walking up from `pwd`; any `AGENT.md` at the repo root. Stop and say so if none resolves — do not run `setup`, `build`, or `upgrade` to "fix" this.
+2. For state — install mode, theme, counts, version fingerprint, drift — prefer the CLI: `geneseed status`, `geneseed version`, `geneseed doctor`, `geneseed diff`. All read-only and cheap ({{LAW}} XV).
+3. To read a specific piece, read the file directly rather than re-deriving from prose ({{LAW}} III): `<harness>/agents/<name>.md`, `<harness>/skills/<name>/SKILL.md`, `<harness>/memory/<file>.md`, `<harness>/notebook/<file>.md`. {{LAWS}} live as numbered `## N. …` sections inside `<harness>/AGENT.md`.
+4. Side-effecting verbs need explicit assent ({{LAW}} XX): `geneseed learn` (writes to {{MEMORY}}), `geneseed context` (refreshes the project's `context.json`), `geneseed web start|stop` (the local browser UI on `127.0.0.1`). `geneseed web status` is read-only.
+5. Never run `setup`, `build`, `upgrade`, `bootstrap`, `update`, `sync-self`, `link`, `unlink`, or `uninstall` as a side effect — these are scope-changing and only run when the user explicitly asks ({{LAW}} II).
+6. The bundle's directory and section names are theme-independent (plain English everywhere); only voice and prose change per theme. Don't pattern-match on flavour words to find files.
+
+## Done when
+- The user's question about the deployed harness is answered from the live install — file paths or CLI output — not from recall.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/git-archaeology.md

@@ -0,0 +1,47 @@
+# {{SKILL}}: git-archaeology
+
+> {{DESC_GIT_ARCHAEOLOGY}}
+
+**Trigger:** you need to learn something *from* the history — when a regression was
+introduced, who last touched a line and why, or where a symbol or string entered the
+codebase. Read-only: this {{SKILL}} investigates, it does not change history (to repair
+or rewrite, use git-rescue.md; to write a new commit, use commit.md).
+
+## Procedure
+1. State the question precisely before touching git: *when did it break*, *why does
+   this code exist*, or *where did this string/symbol come from*. The question picks
+   the lens.
+2. **"When did it break"** → `git bisect`. Find a known-good and known-bad commit, then
+   `git bisect start <bad> <good>`. Drive it with `git bisect run <cmd>` when the test
+   is scriptable — a non-zero exit marks bad — otherwise mark each step by hand. Read
+   the actual command output at each step; never assume a result (universal {{LAW}} III).
+3. **"Why / who"** → `git blame -w -C <file>` (ignore whitespace, follow moved code) to
+   reach the introducing commit, then `git show <sha>` for its message and full diff.
+4. **"Where did this come from"** → the pickaxe: `git log -S'<string>'` for when a
+   string's count changed, `git log -G'<regex>'` for when matching lines changed, or
+   `git log -p -- <path>` to walk a file's history with diffs.
+5. Read the evidence end to end before concluding — the first matching commit is not
+   always the cause. Corroborate across lenses when the answer is consequential
+   (universal {{LAW}} III).
+6. **Reset the investigation state** when done: `git bisect reset` returns to the
+   original HEAD. Confirm the working tree is back where it started (universal {{LAW}} III).
+7. Report the offending/originating commit with its evidence. Do **not** fix the bug
+   inside this investigation — that is a separate, single-purpose change (universal
+   {{LAW}} II); hand off to debug.md or commit.md.
+
+## Done when
+- The question is answered with a specific commit (or commits) and the diff/output that
+  proves it, the bisect state is reset, and the working tree is unchanged.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/git-rescue.md

@@ -0,0 +1,68 @@
+# {{SKILL}}: git-rescue
+
+> {{DESC_GIT_RESCUE}}
+
+**Trigger:** the repository is in a broken or messy state — a bad rebase/merge/reset,
+lost commits, a detached HEAD, a half-finished operation, work stranded in a stash — or
+you intend to deliberately rewrite history (interactive rebase, squash, amend). For
+finding *when/why* something changed without altering history, use git-archaeology.md.
+
+## Procedure
+1. **Stop.** Do not run more commands that could compound the damage. Capture the
+   current state first and read it: `git status`, `git reflog`, and `git stash list`
+   (universal {{LAW}} III). The reflog is the safety net — every HEAD move is recoverable
+   from it.
+2. **Back up before any destructive op.** Create a timestamped marker so the current
+   state is always recoverable: `git branch backup/$(date +%Y%m%d-%H%M%S)`. A branch
+   preserves only *committed* state — if the working tree is dirty, `git stash push -u`
+   (or a WIP commit) first, so a later `reset --hard` cannot destroy uncommitted or
+   untracked work the reflog will never see. Rewriting, resetting, and force-pushing
+   are irreversible acts — never run one without a recovery path in place (universal
+   {{LAW}} IV).
+3. Choose the **minimal** recovery for the actual problem:
+   - *Lost commits / bad reset:* find the SHA in `git reflog`, then
+     `git reset --hard <sha>` (or `git cherry-pick`/`git branch <name> <sha>` to salvage
+     selectively).
+   - *Operation in progress gone wrong:* abort cleanly —
+     `git rebase --abort`, `git merge --abort`, `git cherry-pick --abort`.
+   - *Detached HEAD with work on it:* `git branch <name>` to anchor it before moving.
+   - *Stranded changes:* `git stash list` → `git stash apply <ref>`; recover dropped
+     stashes via their reflog SHA.
+   - *Uncommitted file clobbered:* `git restore --source=<sha> <path>`.
+4. Resolving conflict hunks: find the primary sources for each side — commit
+   messages, PRs, original issues — and understand why each change was made.
+   Preserve both intents where possible; where incompatible, pick the one
+   matching the merge's stated goal and note the trade-off. Never invent new
+   behaviour in a resolution, and — unlike the deliberate `--abort` in step 3
+   that undoes a botched operation on purpose — never `--abort` to escape a
+   conflict you were asked to resolve. Before concluding, run the project's
+   checks (typecheck, tests, format) and fix what the merge broke.
+5. For a **deliberate rewrite** (interactive rebase, squash, fixup, amend): work on a
+   dedicated branch, never a shared one, and keep it the only change in flight
+   (universal {{LAW}} II). A rewrite *creates commits* — amend, squash, `--continue`
+   all do — so present what will change and get the user's acceptance before running
+   it, exactly as for any commit (universal {{LAW}} XX).
+6. Verify the result before declaring success: inspect `git log --oneline`,
+   `git status`, and the diff against the intended state — read the actual output, do
+   not assume the rewrite landed as planned (universal {{LAW}} III).
+7. Push only with the user's explicit, per-push consent — and a history rewrite needs a
+   **force**-push (`--force-with-lease`), which is doubly outward-facing: present what
+   changed and wait for acceptance before pushing (universal {{LAW}} XX / {{LAW}} IV).
+   Never force-push a shared branch without confirming it is safe to do so.
+
+## Done when
+- The repository is in the intended state, verified against actual git output, and the
+  pre-rescue state is still recoverable from the backup branch or the reflog.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/handoff.md

@@ -0,0 +1,29 @@
+# {{SKILL}}: handoff
+
+> {{DESC_HANDOFF}}
+
+**Trigger:** the context window is filling, a session is ending mid-task, or you're passing work to another agent or developer.
+
+## Procedure
+1. Capture the state in the worklog (`WORKLOG.md` or the task's plan file): the goal, what's done, the step in progress, and the exact next step.
+2. Record open decisions, dead ends already ruled out, blockers, and any irreversible changes already made ({{LAW}} XIV) — so the next agent neither re-derives nor repeats them.
+3. Promote any durable fact or correction learned this session into {{MEMORY}} (§4), not just the worklog.
+4. Point to the live artifacts: branch name, changed files, how to run the tests, and where any failure reproduces.
+5. Put a one-line "resume here" pointer at the top so a fresh context picks up in a single read ({{LAW}} XV).
+6. Verify it: re-read the worklog as a cold reader ({{LAW}} III) — goal, progress, next step, and blockers must be answerable from it alone. Fix what isn't.
+
+## Done when
+- A fresh agent can resume from the worklog alone — goal, progress, next step, and blockers are all written down.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.

package/src/skills/herdr.md

@@ -0,0 +1,164 @@
+<!-- Authoring note: this file is deliberately 4-6x the size of its peers — it is the only documentation the agent has for the external `herdr` CLI surface (no man page, no --help in context), so it carries the full command reference inline. Do not split it. -->
+# {{SKILL}}: herdr
+
+> {{DESC_HERDR}}
+
+**Trigger:** you are running inside a herdr-managed pane (`HERDR_ENV=1`) and a task would benefit from another pane — splitting off a server, watching a long-running build, spawning a sibling agent, or reading what a neighbour is doing. If `HERDR_ENV` is unset or not `1`, you are not inside herdr — stop and do not try to control panes from outside.
+
+**Requires:** `HERDR_ENV=1` in the environment and the `herdr` binary on `PATH`.
+
+## What herdr gives you
+
+herdr is a terminal-native agent multiplexer. it organises your work into **workspaces** (project contexts), each holding one or more **tabs** (subcontexts), each holding one or more **panes** (terminal splits running their own process — a shell, an agent, a server, a log stream). every level is controllable from the `herdr` CLI, which talks to the running herdr instance over a local unix socket. the binary is on your `PATH`.
+
+From a single pane you can: see what other panes and agents are doing, create tabs for separate subcontexts, split panes and run commands in them, start servers and watch logs in siblings, wait for specific output before continuing, wait for another agent to finish, and spawn more agent instances.
+
+For the raw protocol and the full reference, see the [socket api docs](https://herdr.dev/docs/socket-api/).
+
+## Procedure
+
+1. **Confirm you are inside herdr.** `echo $HERDR_ENV` should print `1`. If not, stop — the rest of this {{SKILL}} does not apply.
+2. **Orient.** `herdr pane list` shows every pane and which is focused; the focused one is yours, the rest are neighbours. `herdr workspace list` and `herdr tab list --workspace <id>` show the broader layout.
+3. **Pick the smallest move that gets the job done.** Read an existing pane (`pane read`), wait for an event (`wait output` / `wait agent-status`), or spawn a new pane only when you actually need parallel work. Don't open panes you won't use.
+4. **Re-read ids after every create/split.** Workspace ids look like `1`, tab ids like `1:1`, pane ids like `1-1`. They compact when things close, so don't reuse an id you saw earlier — parse the response of `workspace create` / `tab create` / `pane split` (or re-list) to get the current id.
+5. **Close what you opened** once the task is done — leave the workspace as you found it unless the user has asked you to keep a pane around.
+
+## Common operations
+
+### Discover yourself
+
+```bash
+herdr pane list
+herdr workspace list
+herdr tab list --workspace 1
+```
+
+### Read another pane
+
+```bash
+herdr pane read 1-1 --source recent --lines 50
+```
+
+- `--source visible` — current viewport
+- `--source recent` — recent scrollback as rendered in the pane
+- `--source recent-unwrapped` — recent terminal text with soft wraps joined back together (use this when you want to inspect the same transcript `wait output --source recent` matches against)
+- `--format ansi` (or `--ansi`) — rendered ANSI snapshot for TUI feedback loops
+
+### Split a pane and run a command in it
+
+`pane split` prints JSON with the new pane id at `result.pane.pane_id`. Parse it, then run:
+
+```bash
+NEW_PANE=$(herdr pane split 1-2 --direction right --no-focus \
+  | node -e 'console.log(JSON.parse(require("fs").readFileSync(0,"utf8")).result.pane.pane_id)')
+herdr pane run "$NEW_PANE" "npm run dev"
+```
+
+`--direction down` splits below instead. `--no-focus` keeps your terminal context where it is — usually what you want when spawning a sibling.
+
+### Wait for output
+
+Block until specific text appears in a pane. Useful for servers, builds, tests.
+
+```bash
+herdr wait output 1-3 --match "ready on port 3000" --timeout 30000
+herdr wait output 1-3 --match "server.*ready" --regex --timeout 30000
+```
+
+Exit code `1` on timeout. With `--source recent`, matching uses unwrapped text so pane width and soft wrapping never break the match.
+
+### Wait for an agent status
+
+```bash
+herdr wait agent-status 1-1 --status done --timeout 60000
+```
+
+`agent_status` is `idle`, `working`, `blocked`, `done`, or `unknown` — the same distinction the sidebar shows. `done` means the agent finished but you have not looked at that finished pane yet.
+
+### Send text or keys to a pane
+
+```bash
+herdr pane send-text 1-1 "hello"        # text only, no Enter
+herdr pane send-keys 1-1 Enter          # a real key press
+herdr pane run 1-1 "echo hello"         # send-text + Enter in one call
+```
+
+### Tab + workspace management
+
+```bash
+herdr tab create --workspace 1 --label "logs"
+herdr tab rename 1:2 "logs"
+herdr tab focus 1:2
+herdr tab close 1:2
+
+herdr workspace create --cwd /path/to/project --label "api server"
+herdr workspace focus 2
+herdr workspace rename 1 "api server"
+herdr workspace close 2
+
+herdr pane close 1-3
+```
+
+Without `--label`, `workspace create` keeps cwd-based naming and `tab create` keeps numbered naming. `--no-focus` on create/split keeps your current pane focused.
+
+## Recipes
+
+### Run a server and wait until it is ready
+
+```bash
+NEW_PANE=$(herdr pane split 1-2 --direction right --no-focus \
+  | node -e 'console.log(JSON.parse(require("fs").readFileSync(0,"utf8")).result.pane.pane_id)')
+herdr pane run "$NEW_PANE" "npm run dev"
+herdr wait output "$NEW_PANE" --match "ready" --timeout 30000
+herdr pane read "$NEW_PANE" --source recent --lines 20
+```
+
+### Run tests in a sibling pane and inspect the result
+
+```bash
+herdr pane split 1-2 --direction down --no-focus
+herdr pane run 1-3 "cargo test"
+herdr wait output 1-3 --match "test result" --timeout 60000
+herdr pane read 1-3 --source recent --lines 30
+```
+
+### Spawn a new agent and give it a task
+
+```bash
+herdr pane split 1-2 --direction right --no-focus
+herdr pane run 1-3 "claude"
+herdr wait output 1-3 --match ">" --timeout 15000
+herdr pane run 1-3 "review the test coverage in src/api/"
+```
+
+### Coordinate with another agent
+
+```bash
+herdr wait agent-status 1-1 --status done --timeout 120000
+herdr pane read 1-1 --source recent --lines 100
+```
+
+## Notes
+
+- `workspace list/create`, `tab list/create/get/focus/rename/close`, `pane list/get/split`, `wait output`, and `wait agent-status` print JSON on success.
+- `pane read` prints text (or ANSI with `--format ansi`).
+- `pane send-text`, `pane send-keys`, and `pane run` print nothing on success.
+- `workspace create` returns `result.workspace`, `result.tab`, and `result.root_pane`. `tab create` returns `result.tab` and `result.root_pane`. `pane split` returns the new pane at `result.pane.pane_id`.
+- Use `pane read` for output that already exists; use `wait output` for output you expect next.
+
+## Done when
+
+The task that motivated the side pane is finished, its output has been read (or its result captured), and any pane / tab / workspace you opened just for the task has been closed — unless the user asked you to keep it.
+
+## Self-improvement
+
+Close each run with one beat of reflection on the {{SKILL}} itself:
+- A step misled, a needed step was missing, or the trigger fired wrongly — that
+  is a flaw in this file. Propose the exact edit (trigger, procedure, or
+  done-when) and apply it with the user's assent ({{LAW}} II).
+- A lesson that is *not* a flaw in this file goes to {{MEMORY}} only if it
+  clears {{LAW}} VI's bar: it would change how a future session behaves, and a
+  fresh read of the repo would not re-derive it. Update an existing memory over
+  adding one; when in doubt, leave it out.
+- No friction, nothing learned — move on; this loop earns no ceremony. Most
+  runs end here.