@sjawhar/pi-legion 0.0.0 → 8.0.0

package/dist/skills/legion-worker/references/merge-gate.md

@@ -0,0 +1,117 @@
+# The merge gate: review, retro, READY, and the production check
+
+Part of `skill://legion-worker`. Read it when you are the reviewer submitting a review or an
+approval, the implementer recording the production check, or the merger building READY. Every
+path it cites is in sjawhar/legion.
+
+The order, in full: the tester's evidence green → the reviewer's approval of the head →
+retro → the merger's READY → the human merge → the implementer's production check. No role
+removes `.legion/` before the merge: the approved head carries it. The daemon strips whatever
+`.legion/` main still carries from the next issue's branch before any of its roles start
+(dispatch://LEGION-565), so that tree's own merge carries the removal onto the default branch; no
+operator sweep follows. After the approval, only retro's `docs/solutions/` commit leaves it
+standing on its own (*Retro*, below). A conflict-forced merge goes back to the reviewer for a
+confirmation or a new round, as the fingerprint decides (*The reviewer*, below, and
+`skill://legion-worker/references/conflicts-and-rewrites.md`), and any other change to the head
+voids it.
+
+## The reviewer
+
+- The reviewer verifies the `CI`, `Threads`, and `E2E` facts against GitHub directly —
+  never from a handoff — then runs `task(agent="thermonuclear-deep-review")` and
+  `task(agent="thermonuclear-code-quality")` once at that head — the head the round reviews —
+  and records the verdict.
+  Approval is refused while either `E2E (implementer)` or `E2E (tester)` is missing: `REQUEST_CHANGES` naming the missing line.
+  Skip the `Thermo` line entirely on a docs-only PR. Submit **one review per round** —
+  `REQUEST_CHANGES` when any correctness finding stands, otherwise `APPROVE` of the head you
+  reviewed — always named by SHA — carrying every inline comment in that single
+  call: `legion gh -- api --method POST repos/{owner}/{repo}/pulls/{number}/reviews --input body.json`
+  with `commit_id`, `event` (`REQUEST_CHANGES` or `APPROVE`), `body` (with the
+  Legion footer), and a `comments[]` array of `{path, line, side, body}`, one entry per
+  finding — never one `pr review` call per finding (each submission fires a `pr-review` wake).
+  A `COMMENT` decides nothing. After a
+  conflict-forced rebase, compute the fingerprint (*The unchanged-diff check* in
+  `skill://legion-worker/references/conflicts-and-rewrites.md`) at the
+  `commit_id` of your last submitted review and at the new head. Equal and that review was
+  `APPROVE`: submit one more `APPROVE` naming the new head by SHA, its body naming both SHAs
+  and the fingerprint — a confirmation, not a round; no thermo pass, no thread pass. Equal and
+  that review was `COMMENT` or `REQUEST_CHANGES`: continue that round against the new head;
+  nothing restarts. Different: a new round — thermo again, one review.
+- Answer every thread you opened, and every thread a bot opened that is none of Legion's role
+  Apps, as `skill://legion-worker/references/review-threads.md` says; the same reference says
+  when every thread is settled enough to approve, and resolving one never gates your approval.
+
+A reviewer's phase ends with its completion, not with its review. Every round writes a handoff
+and takes this order: write, commit and push the handoff; submit the review of the head that push
+made, by its SHA; then complete. An approval waits for the CI verdict to settle green at that head
+before you submit it, since an approval stands only on green checks and GitHub can dismiss one
+once the head moves, and a verdict that settles red there makes the round's decision a request for
+changes naming the failing checks, unless only review workflows the project declares
+(`projects.<KEY>.review_workflows`) are red on their own findings: then you answer their threads,
+have them resolved with `legion threads resolve` and re-run the failed run, as your role prompt
+says, and approve once it passes. Any other red required workflow is a failing check like any
+other. A request for changes does not wait, since it stands whatever CI says and the issue leaves
+reviewing with it. The verdict is of the checks and workflows the base branch requires, the set
+READY checks: red when one of them failed, and never red for a check the base branch does not
+require. A required check that was cancelled, or that the head's checks
+settled without, leaves no verdict until a later settlement decides it, since a run can be
+cancelled or not yet queued when the head settles; a required workflow's run on the head that is
+still going or has not happened leaves none either. A review of a head the handoff push
+then replaces names a head the pull request no longer has. The daemon moves the issue
+once both are in — the decision GitHub reports and your completion, in either order — so a
+review posted without a completion leaves the issue in reviewing until you finish.
+
+## Retro
+
+- **Retro's commit does not void the reviewer's approval.** After the reviewer approves the
+  head, retro commits its learnings under `docs/solutions/` on top of it; that commit
+  stays, the approval stands, and the tree goes to the merger — never back to the tester or
+  reviewer. Anything else above the approved head does void it, and the merger tells the
+  architect the head must return to review instead of completing. A conflict-forced rebase
+  after retro moves those documents with the branch; retro never re-runs.
+- **Retro brings the PR body's path-derived content up to date before its push.** Whatever the
+  repository's instructions derive from the pull request's changed paths (a checklist named for
+  each class of path, read by a required check), retro recomputes for the whole diff at its commit
+  and writes into the live body before `legion push` (`skill://legion-retro`), since the merger
+  reports a stale body rather than rewriting it. A body edit changes no commit, so the approval
+  stands.
+
+## The merger
+
+- The merger runs `legion threads resolve --pr <n> --repo <owner>/<repo>` (it acts as the same
+  code-writing App as the implementer; resolving a thread changes no commit, so this run never
+  invalidates the approval), does not complete while any `left open` line remains or the command
+  exits 1 (report the thread to the architect instead), then proves that rule with two commands.
+  First `cd -- "$LEGION_WORKSPACE" && jj -R "$LEGION_WORKSPACE" git fetch && jj -R
+  "$LEGION_WORKSPACE" diff --from <approved-sha> --to <tip-sha> --summary`, whose output is quoted
+  in READY (an empty output is quoted as `no file changes above the approved head`); then the same
+  with `'~docs/solutions'` appended, which must print nothing. *The READY packet* is
+  `READY #<n> at <current sha> (approved at <approved sha>) for <KEY> (<pr url>)`
+  (the shape `packages/daemon/internal/prompts/roles/merger.md` defines), then the PR body's
+  `Outcome:` line and its `Not proven / risk:` value — every bullet under that label joined with
+  `; ` on the one READY line, or `none` — quoted from the `## For the reviewer` block at that same
+  head (or one line saying the body carries no brief — the packet still goes out), then the
+  `--summary` output and the PR body's gate facts. The merger sends it as the `summary` of its
+  `handoff_complete` with `ready: true`; the daemon posts it as a `dispatch_message` on the issue,
+  publishes it to the project's merge queue role when one is set, and says on the issue when that
+  role has no live holder. The READY packet names both the implementer's and tester's `E2E` lines;
+  a missing one is reported to the architect instead of completing. Legion never merges.
+
+## After the human merge
+
+- **After a human merges, the implementer verifies in production.**
+  The daemon starts the implementer again once the merge lands; the implementer watches the
+  deploy slot that carries the merge to `production-apply` (or the equivalent publish step),
+  drives the changed path in production through the user's own access path, and records the
+  observation on the PR and the issue before the architect signs off. A staging pass is not
+  this, since a staging gate does not run every resource production does. If the slot fails on
+  the change, the implementer owns the fix and the next slot.
+  The record has three places: the PR body's `Production:` line, one pull-request comment
+  carrying the Legion footer, and a `dispatch_message` on the issue — the reviewer and merger
+  read GitHub, the architect reads the issue. When the deploy that carries the merge has not
+  happened (a shared profile still holding the previous plugin release, a daemon still running
+  the previous commit, a slot nobody has run), open a `dispatch_ask` that starts with the
+  production gap and why it matters, then names the required install or restart step, its risk,
+  and outcome-named options. Keep the `Production:` line at `pending <what is missing>`, and
+  complete the check once the human answers. Never record a staging pass as the production check,
+  and never let the architect sign off on a `pending` line.

package/dist/skills/legion-worker/references/pr-body.md

@@ -0,0 +1,146 @@
+# PR body, proofs, and the simplify pass
+
+Part of `skill://legion-worker`. Read it before you write or edit any line of the pull request
+body, put a `proof` array in a handoff, verify another phase's proof, or run the simplify pass.
+Every path it cites is in sjawhar/legion.
+
+## The pull request body template
+
+The implementer writes the PR body from this template from the moment the PR opens, and every
+later phase keeps it current rather than replacing it:
+
+```
+## For the reviewer
+
+**Outcome:** <one sentence a user of this repository would recognise: what someone can now do, or what stops going wrong>
+**Why:** <the problem, one or two sentences, ending with the Dispatch key in parentheses — the key only, never a URL>
+**Change:**
+- <two to five bullets, each one behaviour a user or operator meets, never a file name>
+**Look at first:** <one to three `path:line` places where a wrong decision would hurt> (the reviewer writes this line)
+**Proven by:** <the `E2E (implementer)` line's surface and run, one line>
+**Not proven / risk:**
+- <one line per claim recorded as unproven before READY>, or the single word `none` (the reviewer writes this line; `none` is invalid while such a claim stands)
+**Size:** <files changed, +added/−removed>
+
+## Verification
+
+**CI:** `Tests` run <run-id> — jobs lint, typecheck, test all success at <head-sha>; `PR Title` run <run-id> — job pr-title success at <head-sha>.
+
+**Threads:** <n> resolved, 0 unresolved. Each disposed individually, never in bulk:
+- Thread <id>: fixed in <commit-sha> — <one line>.
+- Thread <id>: not a defect — <reason>.
+`legion threads resolve --pr <n> --repo <owner>/<repo>`, run after the push that made <head-sha>:
+resolved <thread URL> — its opener's acceptance
+resolved <thread URL> — the Legion reviewer's acceptance of a bot's thread
+left open <thread URL> — newest reply by <login> is not an acceptance
+left open <thread URL> — newest reply by <login> is an unsubmitted draft in a pending review
+left open <thread URL> — newest reply by <login> is not its opener's or the Legion reviewer's acceptance
+
+**Thermo:** `ce-simplify-code` once at <head-sha>: <0 applied | applied → new head <sha>>; thermonuclear pair at the reviewed head <sha>:
+<verdict>. (omitted entirely on a docs-only PR — there is no code for either pass, so neither runs)
+
+**E2E (implementer):** <surface> — ran `<command or run id>`, observed <result>, at head <sha>.
+Negative control: <deliberately broken input or call> → <refusal or failure observed>.
+
+**E2E (tester):** <surface> — ran `<command or run id>`, observed <result>, at head <sha>.
+Negative control: <deliberately broken input or call> → <refusal or failure observed>.
+Verified the implementer's proof by <re-running its command | driving the same surface independently>.
+
+**Production:** <what was checked in production, how, what was observed> — merge commit <sha>.
+(written by the implementer after the merge lands; `pending <what is missing>` until then)
+
+**Fast-follow:** <one named cleanup item and where it will land>, or "none".
+
+**Chain:** stacked on <base bookmark> frozen at <sha> / not stacked.
+```
+
+## The brief for the human
+
+`## For the reviewer` is written for the person who merges; `## Verification` below it stays the
+ledger the reviewer and merger check against GitHub. The implementer writes `Outcome`, `Why`,
+`Change`, `Proven by`, and `Size` when the pull request opens, and keeps them true after every
+push; `Outcome` is a sentence a user of the repository would recognise, never "fix bug" or a file
+name, and `Why` ends with the Dispatch key, never a URL. The reviewer writes `Look at first` and
+`Not proven / risk` at each round, into the live body (`legion gh -- api
+repos/{owner}/{repo}/pulls/{number} --jq .body`, edit, then `--method PATCH ... -F body=@body.md`);
+`Not proven / risk` copies every claim recorded as unproven before READY — the tester's
+`failures`, the reviewer's own review, any proof-check comment already on the pull request —
+word for word, and `none` is a finding while one stands. The merger quotes `Outcome` and
+`Not proven / risk` from the body at the head its READY packet names
+(*The READY packet* in `skill://legion-worker/references/merge-gate.md`); a stale `Outcome` that no
+longer describes the diff is a finding against the implementer, not a line the merger rewrites.
+
+## What a proof is
+
+**A proof** is the changed behaviour exercised on the surface a user reaches it through, recorded
+as the exact command or run id, what was observed, the head SHA, and one negative control —
+a deliberately broken input or call and the refusal or failure observed. The surface is
+**production-like** — the repository's real-process test harness and fixtures, a sandbox
+repository, a real browser, a devN stack, staging, or a local stack with real migrations, one that
+has the resource the change touches — and each `E2E` line carries a **link** to that run,
+screenshot, or e2e; human review does not replace user-facing verification, and a green unit suite
+is not it. A unit or integration test is a regression lock, never proof of a criterion. The agent
+that develops the change proves it this way before the merge, and whatever blocks that proof is
+fixed, not skipped (*When no surface reaches the changed path*, below). The implementer's proof
+and the tester's proof below are both this proof.
+
+## The rules every phase's evidence follows
+
+- **The implementer proves the change before its phase completes, and writes the `E2E (implementer)` line when the pull request opens.**
+  The proof is the one defined above. It goes into `.legion/<issue>/implement.json` as the required `proof`
+  array (`handoff_write` for phase `implement` refuses a payload without one, or with a blank or
+  whitespace-only field, and names the field), and into the PR body, because the reviewer and the
+  merger verify facts on GitHub and never from a handoff.
+- **The tester verifies the implementer's proof and adds its own `E2E (tester)` line.** It re-runs
+  the implementer's command or drives the same surface independently, and records the verdict in
+  `.legion/<issue>/test.json` as `implementerProof` (`{verdict, how}`).
+  A test handoff whose predecessor carried no proof is a test failure, not a gap for the tester to fill:
+  record it in `failures` with `implementerProof.verdict: "rejected"`, complete the phase with
+  `verdict: "fail"`, and the daemon returns the issue to the implementer — the agent that developed the change owns
+  proving it (`handoff_write` for phase `test` refuses a rejected verdict, or `failed > 0`,
+  with no recorded failure). Otherwise, add your own proof before completing — a proof as defined
+  above — as the `E2E (tester)` line and the `proof` array `handoff_write` for
+  phase `test` requires whenever you report no failure. A code path whose first execution is after merge — a
+  deploy workflow's inline step, a post-merge helper, a production-only resource — is untested
+  until the implementer has executed it against a devN stack; if no surface can reach it, the
+  tester names that missing surface as the blocker instead of passing the phase. Environment or
+  secret-scrub evidence (e.g. "`LEGION_*`/`DISPATCH_*`/`ENVOY_*` unset") is recorded once, in
+  `.legion/<issue>/test.json`, and only when the issue's acceptance criteria call for it — never
+  re-pasted into the PR body each round. After a conflict-forced rebase, compute the
+  fingerprint (*The unchanged-diff check* in
+  `skill://legion-worker/references/conflicts-and-rewrites.md`) at the head your `E2E` line
+  names and at the new head. Equal: re-run only the
+  bare gates — the repository's CI green at the new head and its smoke check — and change the
+  `E2E` line's head to the new SHA with
+  `rebase re-check <old-sha> → <new-sha>: fingerprint unchanged, bare gates only`; the
+  real-surface verification is not repeated. Different: a full test round.
+- **The implementer runs `skill://ce-simplify-code` once per pull request, in its first
+  implementing round, after its own proof and before it completes that round, when the diff
+  touches runtime code; a docs-only diff gets none.** The daemon starts no implementing round
+  between a clean review and the approval, so this is the one slot before the tester and the
+  reviewer read the head; a later round answering a review runs no second pass. It is scoped to
+  the pull request's own diff at that head: nothing applied leaves the head as it is; applied →
+  the implementer re-runs the repository's checks and its own proof on the applied head for the
+  surface the simplify diff touched, since a refactor that "preserves behaviour" is a claim until
+  it is executed, and re-cites the `CI` line and `E2E (implementer)` there before it completes.
+  That cost is why 0-applied is the expected outcome and a pass that applies is spent sparingly.
+  The reviewer's pair runs at the head each round reviews. Record both in the `Thermo` line.
+- **No deferrals** is the body's rule (*PR body, review, and the merge gate* in
+  `skill://legion-worker`): the `Fast-follow:` line holds naming, duplication, or wording cleanup
+  only. A base frozen for others to stack on is never rewritten (*Rewriting pushed commits* in
+  `skill://legion-worker/references/conflicts-and-rewrites.md`); the `Chain` line records it.
+- **GitHub refuses a pull request body over 65,536 characters.** Each verification round links its
+  evidence (the run, the comment) rather than inlining it once the body passes about 48,000
+  characters; the `Production` line's record always links.
+
+## When no surface reaches the changed path
+
+No surface reaches the changed path is a report to the architect, never a reason to complete the phase.
+Say which surface is missing and what it would have to do — a rig that can spawn the role, a
+sandbox that holds the resource, a credential, a command that does not exist yet — and send it to
+the architect with `envoy_publish` to its role topic. The architect creates a child issue in this
+tree to build it (infrastructure, tooling, or a skill) and resumes you once it lands. A code path
+whose first execution would be after the merge — a deploy
+workflow's inline step, a post-merge helper, a production-only resource — is untested until you
+have executed it somewhere production-like; completing with a unit-test-only handoff is the
+failure this rule exists to stop.

package/dist/skills/legion-worker/references/review-threads.md

@@ -0,0 +1,101 @@
+# Review threads
+
+Part of `skill://legion-worker`. Read it when you reply to, accept, or resolve a review thread,
+or run `legion threads resolve`: the implementer after every push that answers a review, the
+merger before READY, and the reviewer, who answers threads on every re-review and runs the command
+only when a review workflow the project declares is red on a bot's findings.
+Every path it cites is in sjawhar/legion.
+
+- **Threads are dispositioned individually, never resolved in bulk.** Every open review
+  thread gets its own line naming the fixing commit or the reason it isn't a defect. The
+  reviewer answers each thread it opened, and each thread a bot opened that is none of Legion's
+  role Apps, with exactly one of `Accepted: fixed in <commit> — <one line>`,
+  `Accepted: not a defect — <reason>`, or `Still open: <what remains>`; nothing else is an
+  acceptance, and nobody replies after an `Accepted:` (any later reply that is not itself an
+  `Accepted:` — the opener's own follow-up included — leaves the thread open, because resolution
+  considers only the newest comment). The review App can reply on a thread but cannot resolve it:
+  GitHub grants resolving a review thread to the pull request's author, and the implementer opens
+  every Legion pull request (`docs/site/src/content/docs/legion/running-legion.md`, "The two
+  GitHub Apps"). In the reviewer's pane (`LEGION_ROLE=reviewer`), `legion threads resolve` asks
+  the daemon instead (`POST /legion/v1/threads/resolve`), which resolves as the implementer's App
+  only the threads a bot outside Legion's role Apps opened whose newest submitted comment is the
+  reviewer's `Accepted:`, on the pull request of the reviewer's own issue, and prints the same
+  lines; the reviewer never holds the implementer's token. A thread whose newest comment is a
+  draft in the implement App's pending review (the implementer's or the merger's: GitHub shows it
+  to that App alone, as which the daemon reads) is left open and never named: the command prints
+  only how many there are (`<n> unresolved threads hold the implement App's pending draft and
+  were left open`) and exits 1, as it does on a refusal. Report that count to the architect before
+  you spend your one re-run of the failed workflow; the architect sends the issue back so the
+  implementer submits or discards its pending review. Once the review is submitted, the
+  implementer's reply is the thread's newest comment, which leaves it open: answer the thread
+  again, then run the command again. Once the review is discarded, your `Accepted:` is the newest
+  comment again, and running the command again closes the thread.
+  When `LEGION_GRANT_FILE` or `LEGION_GRANT` is set, use `legion threads resolve --pr <number> --repo <owner>/<repo>`.
+  When neither is set, add `--gh` to that command, which applies the fallback's rule below through
+  your own `gh`; where no `legion` command is installed, use `gh api graphql` with the session's
+  GitHub credential and the fallback below.
+  In a Legion pane, the **implementer** runs the command after every push that answers a review
+  and before its `handoff_complete`, and pastes its output, stamped with the head it just pushed, into
+  the `Threads` section. The output is then recorded against the head the reviewer will read, and
+  nothing reads thread state before the implementer's completion. The command resolves each
+  unresolved thread whose newest submitted comment is the opener's own `Accepted:` reply. On a
+  thread a bot account opened that is none of Legion's role Apps (the daemon names them, keyed by
+  App role), the Legion reviewer's `Accepted:` also closes it. GitHub cannot tell a CI bot, which
+  never accepts, from a person whose `gh` is routed to an App, so the reviewer adjudicates such a
+  finding, and it may accept one an App-routed person raised. The subject of a finding never
+  closes it: the implementer's `Fixed in <commit>: …` or `Declined: …` answers a thread and closes
+  none. A thread either Legion App opened, a reviewer's finding included, still needs its opener's
+  `Accepted:`. It makes one `resolveReviewThread` per
+  thread, prints `resolved <url> — <whose acceptance>` (its opener's, or the Legion reviewer's on a
+  bot's thread, so the ledger shows which) or `left open <url> — newest reply by <login> is …`
+  naming why, and exits 1 naming the thread's URL and GitHub's message when GitHub refuses one.
+
+  Without a grant, page through `reviewThreads`, skip `isResolved: true`, and compare the opener
+  with the newest comment. Query shape, inside `repository { pullRequest { … } }`:
+
+  ```graphql
+  reviewThreads(first: 100, after: $after) {
+    pageInfo { hasNextPage endCursor }
+    nodes {
+      id isResolved
+      opener: comments(first: 1) { nodes { author { __typename login } } }
+      newest: comments(last: 1) { nodes { author { __typename login } body state } }
+    }
+  }
+  ```
+
+  Resolve only when the newest comment is submitted, its `author` is the opener's account (the same
+  `__typename` and `login`: a login alone is a string anyone may register), and its `body`, after
+  removing leading spaces, tabs, CR, and LF, begins `Accepted:`. Without a
+  grant nothing names Legion's own App logins, so this route closes a bot's thread only on its
+  opener's `Accepted:`: leave one the Legion reviewer accepted for the implementer's or merger's
+  run in a pane, or report it. For each thread to resolve:
+
+  ```graphql
+  mutation($threadId: ID!) {
+    resolveReviewThread(input: { threadId: $threadId }) { thread { isResolved } }
+  }
+  ```
+
+  Re-read `reviewThreads` and confirm that thread's `isResolved` is true. In either route, report
+  a refused resolution to the architect, which opens an ask for a human to resolve the thread by
+  hand — never skip it silently. The merger runs the command once more before its READY
+  completion and does not complete while any `left open` line remains. That run is where every accepted
+  thread's resolution is guaranteed, since the merge queue's gate counts the unresolved threads at
+  the head. Acceptances posted after the implementer's last run are resolved here.
+
+- **The reviewer, on a re-review.** When you re-review after a corrective push, answer every
+  thread you opened, and every thread a bot opened that is none of Legion's role Apps, in one of
+  the three forms above — `Accepted:` is the only reply `legion threads resolve` acts on. A bot's
+  finding you cannot accept becomes your own: leave it `Still open:` and request changes.
+  Approve once each of those threads has your own `Accepted:` as its newest submitted comment,
+  whether or not GitHub shows the thread resolved yet, and every other unresolved thread its
+  opener's (read the newest comments with `gh api graphql`, never from the PR body). Another
+  opener's thread that a person resolved with GitHub's button, with no `Accepted:`, gates nothing:
+  neither `legion threads resolve` nor the merge queue's gate counts a resolved thread. Resolution
+  is the pull request author's App's, so your approval never waits on it, except when a review
+  workflow the project declares (`projects.<KEY>.review_workflows`) is red on its findings: such a
+  workflow passes on a re-run only once its threads are resolved, so you run `legion threads
+  resolve` (the daemon resolves the bot threads you accepted) and re-run the failed run before you
+  approve, as your role prompt says.
+  The merger resolves accepted threads that remain open before its READY completion.

package/dist/skills/legion-worker/references/systematic-rename.md

@@ -0,0 +1,19 @@
+# Strategy: Systematic Rename
+
+When a repo, package, or URL is renamed across a codebase.
+
+## Checklist
+
+1. **Scope by file type** — grep all text-bearing extensions, not just the obvious ones:
+   - Source code (`.ts`, `.js`, `.py`, `.sh`) — functional, must update
+   - CI/CD configs (`.yml`, `.yaml`) — functional, must update
+   - Documentation (`.md`) — correctness, should update
+   - Config files (`.json`, `.toml`) — check but may be immutable
+
+2. **Classify matches as mutable vs immutable** — historical records (transcripts, test snapshots, progress logs) must NOT be modified. Changing them falsifies history.
+
+3. **Check comments for semantic context** — a comment mentioning the old name may still be correct in intent. Update the name but preserve the reasoning.
+
+4. **Verify with grep before AND after** — capture pre-edit state as a baseline for comparison.
+
+5. **Use `jj diff --git`** for verification — plain `jj diff` without color concatenates old/new text confusingly (e.g., `old-nameNEW-name` without color codes).

package/dist/skills/thermonuclear-code-quality/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cursor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/skills/thermonuclear-code-quality/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: thermonuclear-code-quality
+description: Run a strict maintainability review for abstraction quality, oversized files, and ad-hoc branching growth. Use for a thermonuclear code-quality review or a deep maintainability audit.
+disable-model-invocation: true
+---
+
+# Thermonuclear Code Quality
+
+Use this skill for an unusually strict review focused on implementation quality, maintainability, abstraction quality, and codebase health.
+
+Look for structural simplifications that preserve behavior while making the implementation smaller, more direct, and easier to maintain. Do not stop at local cleanup when a coherent simplification is available.
+
+## Core Prompt
+
+Start from this baseline:
+
+> Perform a deep code quality audit of the current branch's changes.
+> Rethink how to structure / implement the changes to meaningfully improve code quality without impacting behavior.
+> Work to improve abstractions, modularity, reduce Spaghetti code, improve succinctness and legibility.
+> Restructure when there is a clear path to a simpler implementation.
+> Be thorough and rigorous. Verify claims before reporting them.
+
+## Non-Negotiable Additional Standards
+
+Apply the baseline prompt above, plus these explicit review rules:
+
+0. **Be ambitious about structural simplification.**
+   - Do not stop at "this could be a bit cleaner."
+   - Look for opportunities to reframe the change so that whole branches, helpers, modes, conditionals, or layers disappear entirely.
+   - Prefer the solution that makes the code feel inevitable in hindsight.
+   - Assume there is often a "code judo" move available: a re-organization that uses the existing architecture more effectively and makes the change dramatically simpler and more elegant.
+   - If you see a path to delete complexity rather than rearrange it, push hard for that path.
+
+1. **Do not let a PR push a file from under 1k lines to over 1k lines without a very strong reason.**
+   - Treat this as a strong code-quality smell by default.
+   - Prefer extracting helpers, subcomponents, modules, or local abstractions instead of letting a file sprawl past 1000 lines.
+   - If the diff crosses that threshold, explicitly ask whether the code should be decomposed first.
+   - Depart from this only if there is a compelling structural reason and the resulting file remains well organized.
+
+2. **Do not allow random spaghetti growth in existing code.**
+   - Be highly suspicious of new ad-hoc conditionals, scattered special cases, or one-off branches inserted into unrelated flows.
+   - If a change adds "weird if statements in random places", treat that as a design problem, not a stylistic nit.
+   - Prefer pushing the logic into a dedicated abstraction, helper, state machine, policy object, or separate module instead of tangling an existing path.
+   - Call out changes that make the surrounding code harder to reason about, even if they technically work.
+
+3. **Bias toward cleaning the design, not just accepting working code.**
+   - If behavior can stay the same while the structure becomes meaningfully cleaner, push for the cleaner version.
+   - Do not rubber-stamp "it works" implementations that leave the codebase messier.
+   - Strongly prefer simplifications that remove moving pieces altogether over refactors that merely spread the same complexity around.
+
+4. **Prefer direct, boring, maintainable code over hacky or magical code.**
+   - Treat brittle, ad-hoc, or "magic" behavior as a code-quality problem.
+   - Be skeptical of generic mechanisms that hide simple data-shape assumptions.
+   - Flag thin abstractions, identity wrappers, or pass-through helpers that add indirection without buying clarity.
+
+5. **Push hard on type and boundary cleanliness when they affect maintainability.**
+   - Question unnecessary optionality, `unknown`, `any`, or cast-heavy code when a clearer type boundary could exist.
+   - Prefer explicit typed models or shared contracts over loosely-shaped ad-hoc objects.
+   - If a branch relies on silent fallback to paper over an unclear invariant, ask whether the boundary should be made explicit instead.
+
+6. **Keep logic in the canonical layer and reuse existing helpers.**
+   - Call out feature logic leaking into shared paths or implementation details leaking through APIs.
+   - Prefer existing canonical utilities/helpers over bespoke one-offs.
+   - Push code toward the right package, service, or module instead of normalizing architectural drift.
+
+7. **Treat unnecessary sequential orchestration and non-atomic updates as design smells when the cleaner structure is obvious.**
+   - If independent work is serialized for no good reason, ask whether the flow should run in parallel instead.
+   - If related updates can leave state half-applied, push for a more atomic structure.
+   - Do not over-index on micro-optimizations, but do flag avoidable orchestration complexity that makes the implementation more brittle.
+
+## Primary Review Questions
+
+For every meaningful change, ask:
+
+- Is there a "code judo" move that would make this dramatically simpler?
+- Can this change be reframed so fewer concepts, branches, or helper layers are needed?
+- Does this improve or worsen the local architecture?
+- Did the diff add branching complexity where a better abstraction should exist?
+- Did a previously cohesive module become more coupled, more stateful, or harder to scan?
+- Is this logic living in the right file and layer?
+- Did this change enlarge a file or component past a healthy size boundary?
+- Are there repeated conditionals that signal a missing model or missing helper?
+- Is the implementation direct and legible, or does it rely on special cases and incidental control flow?
+- Is this abstraction actually earning its keep, or is it just a wrapper?
+- Did the diff introduce casts, optionality, or ad-hoc object shapes that obscure the real invariant?
+- Is this logic living in the canonical layer, or did the diff leak details across a boundary?
+- Is this orchestration more sequential or less atomic than it needs to be?
+
+## What to Flag Aggressively
+
+Escalate findings when you see:
+
+- A complicated implementation where a cleaner reframing could delete whole categories of complexity.
+- Refactors that move code around but fail to reduce the number of concepts a reader must hold in their head.
+- A file crossing 1000 lines due to the PR, especially if the new code could be split out.
+- New conditionals bolted onto unrelated code paths.
+- One-off booleans, nullable modes, or flags that complicate existing control flow.
+- Feature-specific logic leaking into general-purpose modules.
+- Generic "magic" handling that hides simple structure and makes the code harder to reason about.
+- Thin wrappers or identity abstractions that add indirection without simplifying anything.
+- Unnecessary casts, `any`, `unknown`, or optional params that muddy the real contract.
+- Copy-pasted logic instead of extracted helpers.
+- Narrow edge-case handling implemented in the middle of an already busy function.
+- Refactors that technically pass tests but make the code less modular or less readable.
+- "Temporary" branching that is likely to become permanent debt.
+- Bespoke helpers where the codebase already has a canonical utility for the job.
+- Logic added in the wrong layer/package when it should live somewhere more central.
+   - Sequential async flow where independent work could use simpler parallel execution.
+- Partial-update logic that leaves state less atomic than necessary.
+
+## Preferred Remedies
+
+When you identify a code-quality problem, prefer suggestions like:
+
+- Delete a whole layer of indirection rather than polishing it.
+- Reframe the state model so conditionals disappear instead of getting centralized.
+- Change the ownership boundary so the feature becomes a natural extension of an existing abstraction.
+- Turn special-case logic into a simpler default flow with fewer exceptions.
+- Extract a helper or pure function.
+- Split a large file into smaller focused modules.
+- Move feature-specific logic behind a dedicated abstraction.
+- Replace condition chains with a typed model or explicit dispatcher.
+- Separate orchestration from business logic.
+- Collapse duplicate branches into a single clearer flow.
+- Delete wrappers that do not meaningfully clarify the API.
+- Reuse the existing canonical helper instead of introducing a near-duplicate.
+- Make type boundaries more explicit so the control flow gets simpler.
+- Move the logic to the package/module/layer that already owns the concept.
+- Parallelize independent work when that also simplifies the orchestration.
+- Restructure related updates into a more atomic flow when partial state would be harder to reason about.
+
+Do not be satisfied with "maybe rename this" feedback when the real issue is structural.
+Do not be satisfied with a merely cleaner version of the same messy idea if there is a plausible path to a much simpler idea.
+
+## Review Tone
+
+Be direct, serious, and demanding about quality.
+Do not be rude, but do not soften major maintainability issues into mild suggestions.
+If the code makes the codebase messier, say so.
+If the implementation missed a substantial simplification, state it.
+
+Good phrases:
+
+- `this pushes the file past 1k lines. can we decompose this first?`
+- `this adds another special-case branch into an already busy flow. can we move this behind its own abstraction?`
+- `this works, but it makes the surrounding code more spaghetti. let's keep the behavior and restructure the implementation.`
+- `this feels like feature logic leaking into a shared path. can we isolate it?`
+- `this abstraction seems unnecessary. can we just keep the direct flow?`
+- `why does this need a cast / optional here? can we make the boundary more explicit instead?`
+- `this looks like a bespoke helper for something we already have elsewhere. can we reuse the canonical one?`
+- `i think there's a code-judo move here that makes this much simpler. can we reframe this so these branches disappear?`
+- `this refactor moves complexity around, but doesn't really delete it. is there a way to make the model itself simpler?`
+
+## Output Expectations
+
+Prioritize findings in this order:
+
+1. Structural code-quality regressions
+2. Missed opportunities for dramatic simplification / code-judo restructuring
+3. Spaghetti / branching complexity increases
+4. Boundary / abstraction / type-contract problems that make the code harder to reason about
+5. File-size and decomposition concerns
+6. Modularity and abstraction issues
+7. Legibility and maintainability concerns
+
+Do not flood the review with low-value nits if there are larger structural issues.
+Prefer a smaller number of high-conviction comments over a long list of cosmetic notes.
+
+## Approval Bar
+
+Do not approve merely because behavior seems correct.
+The bar for approval is:
+
+- no clear structural regression
+- no obvious missed opportunity to make the implementation dramatically simpler when such a path is visible
+- no unjustified file-size explosion
+- no obvious spaghetti-growth from special-case branching
+- no hacky or magical abstraction that makes the code harder to reason about
+- no unnecessary wrapper/cast/optionality churn obscuring the real design
+- no clear architecture-boundary leak or avoidable canonical-helper duplication
+- no missed opportunity for an obvious decomposition that would materially improve maintainability
+
+Treat these as presumptive blockers unless the author can justify them with evidence:
+
+- the PR preserves a lot of incidental complexity when there is a plausible code-judo move that would delete it
+- the PR pushes a file from below 1000 lines to above 1000 lines
+- the PR adds ad-hoc branching that makes an existing flow more tangled
+- the PR solves a local problem by scattering feature checks across shared code
+- the PR adds an unnecessary abstraction, wrapper, or cast-heavy contract that makes the design more indirect
+- the PR duplicates an existing helper or puts logic in the wrong layer when there is a clear canonical home
+
+If those conditions are not met, leave explicit, actionable feedback and push for a cleaner decomposition.

package/dist/skills/thermonuclear-deep-review/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cursor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.