[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M77MAKAPXGCDCP63QK26VCQR":3,"skill-same:01M77MAKAPXGCDCP63QK26VCQR":56},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":30,"ownerDescription":6,"updatedAt":31,"install":32,"resources":45},"01M77MAKAPXGCDCP63QK26VCQR","doc-and-modernize",null,"Two related workflows for a locally-cloned codebase, in one skill. Documentation mode produces a single, comprehensive, verifiable architecture document primarily by reading files on disk (local-first) — use it whenever the user wants to understand, map, document, research, or onboard onto a codebase (\"research this repo\", \"write up the architecture\", \"do an architecture deep dive\", \"document how this codebase works\", \"map the system design\", \"create an onboarding doc\"). Modernization mode generates a phased plan to modernize, migrate, upgrade, or rewrite a legacy system (\"modernize this\", \"plan the migration\", \"how would we rewrite this\", \"how do we get off this legacy stack\"); if no architecture document exists yet it first runs Documentation mode, then continues straight through to the plan. It assumes the legacy stack may be dead, runs a time-boxed feasibility spike, and picks the highest achievable rung on a safety ladder instead of demanding a fully-green legacy CI gate up front.","Reihantt6\u002Fsns-myagent","Reihantt6","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F219822095?v=4","01M77KK94PV8B7C2D9XWXNS8DJ","Mohamad Reihan tegar prasetya","01M77KK958QFMTHYXGXFV7KZ79",2,"MIT","https:\u002F\u002Fgithub.com\u002FReihantt6\u002Fsns-myagent\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fdoc-and-modernize\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: doc-and-modernize\ndescription: >-\n  Two related workflows for a locally-cloned codebase, in one skill.\n  Documentation mode produces a single, comprehensive, verifiable architecture\n  document primarily by reading files on disk (local-first) — use it whenever the user wants to\n  understand, map, document, research, or onboard onto a codebase (\"research\n  this repo\", \"write up the architecture\", \"do an architecture deep dive\",\n  \"document how this codebase works\", \"map the system design\", \"create an\n  onboarding doc\"). Modernization mode generates a\n  phased plan to modernize, migrate, upgrade, or rewrite a legacy system\n  (\"modernize this\", \"plan the migration\", \"how would we rewrite this\", \"how do\n  we get off this legacy stack\"); if no architecture document exists yet it\n  first runs Documentation mode, then continues straight through to the plan. It\n  assumes the legacy stack may be dead, runs a time-boxed feasibility spike, and\n  picks the highest achievable rung on a safety ladder instead of demanding a\n  fully-green legacy CI gate up front.\n---\n\n# Documentation & Modernization\n\nTwo complementary workflows for a repository the user already has checked out\nlocally, bundled as one skill:\n\n- **Documentation mode** — produce one definitive, cited architecture document\n  from the code on disk. Ideal for onboarding, system-design maps, or as the\n  evidence base for a modernization effort.\n- **Modernization mode** — turn that architecture into a phased, safety-laddered\n  plan to upgrade, migrate, or rewrite a legacy system.\n\n## Mode selection\n\n- If the user wants to **understand, document, map, research, or onboard onto** a\n  codebase, run **Documentation mode**.\n- If the user wants to **modernize, migrate, upgrade, or rewrite** a system, run\n  **Modernization mode**. Modernization mode is self-sufficient: if no\n  architecture document exists yet, it runs the **Documentation mode** workflow\n  first (in the same pass), then continues straight through to the plan.\n\nWhen in doubt, produce the architecture document first — it is the audited\nevidence base both modes rely on.\n\n## Documentation mode\n\nGenerate one definitive, cited architecture document for a repository the user\nalready has checked out locally. The goal is a writeup someone could hand to a\nnew engineer as their onboarding reference — broad enough to cover the whole\nsystem, deep enough on the hard parts to be useful, and trustworthy because\nevery claim traces back to a file on disk.\n\n### Why local-first\n\nReading from the local checkout (not the GitHub API or the web) is the deliberate\n**default**. It is faster, free, avoids rate limits, and — most importantly — it\ndescribes *the exact code in front of you* rather than whatever `main` happens\nto look like remotely. The one tradeoff is that remote-only facts (star counts,\nfull CI run history, sibling repos) aren't visible. That's fine: state those as\nout-of-scope or mark them `[UNVERIFIED]` rather than guessing.\n\nLocal-first is not local-*never*-remote: a web\u002FAPI lookup is a deliberate\n**last-resort fallback**, reserved for a fact that genuinely cannot be determined\nfrom disk and that materially matters to the document. When you do reach for it,\nflag the result clearly (e.g. `[UNVERIFIED]` \u002F sourced-remotely) so the reader\nknows it didn't come from the checkout, and never let it become the easy path\nthat displaces reading the code on disk.\n\n### Workflow\n\n1. **Establish identity first.** Run `git remote -v`, `git branch --show-current`,\n   and `git log -1` so the document is anchored to a specific remote, branch, and\n   commit. A reader must be able to tell which snapshot this describes. Remote\n   URLs can contain embedded credentials (e.g. `https:\u002F\u002F\u003Ctoken>@github.com\u002F...`)\n   — **redact any credentials\u002Ftokens** from the URL before recording it in the\n   document.\n2. **Detect, don't assume.** Read the real manifests (`go.mod`, `package.json`,\n   `Cargo.toml`, `pyproject.toml`, `pom.xml`, etc.), the `Makefile`\u002Ftask runner,\n   CI config, and any repo-specific agent or contributor docs (`AGENTS.md`,\n   `CONTRIBUTING`, `README`, `docs\u002F`). These are the source of truth for the tech\n   stack and commands — prefer them over your prior knowledge of the framework.\n3. **Map breadth, then drill into depth.** First build the whole-repo map (the\n   three lenses below), then pick the 2-3 hardest subsystems and go deep on them.\n4. **Verify as you go.** Open the files you cite. If you reference a line number,\n   you should have actually read that line. Unsupported claims are worse than\n   omissions here — the whole value of this document is that it can be trusted.\n\n### Output structure\n\nProduce a **single Markdown file** with the sections below, in this order. Adapt\nthe headings to the actual project (a CLI tool has no \"frontend\" lens — fold that\nslot into whatever matters for that repo), but keep the three-lens shape and the\nverification discipline.\n\n#### Part 1 — Whole-repo technical deep-dive\n- What the repository is (one paragraph, cited to README).\n- Tech-stack detection table: layer | technology | evidence (file+line).\n- Entry points (backend, frontend, CLI — whatever applies).\n- **Commands & Verification Inventory** — a table of the canonical project\n  commands (`command | purpose | evidence`), verified against the task runner \u002F\n  manifests \u002F CI config, not guessed. Cover build, run\u002Fserve, test (and how to\n  run a single test), lint, format, and — where they exist — typecheck,\n  end-to-end\u002Fsmoke, contract, and any other gate commands, plus the CI\n  workflow(s) that run them and on what trigger. **Also record whether CI is\n  *enforced*** — i.e. whether any workflow is a **required status check \u002F\n  branch-protection rule** that actually blocks merges, versus one that merely\n  runs — since that distinction is a manual, human-configured setting that\n  Modernization mode must surface, not assume. Enforcement usually cannot be\n  determined from the local checkout alone: ask the user, or mark it\n  `[UNVERIFIED]` unless confirmed from an authoritative source (any remote\n  lookup is a flagged last resort, per the local-first rule above). This\n  inventory is the source of\n  truth that downstream planning (Modernization mode) cites so its exit\n  criteria are runnable, not aspirational. Detect these per-ecosystem (npm\u002Fyarn\u002F\n  pnpm, `make`, `just`, `cargo`, `go`, `poetry`\u002F`tox`\u002F`nox`, `gradle`\u002F`maven`,\n  etc.) — do not assume a stack. Mark any command you could not verify\n  `[UNVERIFIED]`.\n- Directory layout for each major area, with a one-line purpose per directory.\n- **Deployment & Runtime Surface** — a table of every place the language\u002Fruntime\n  and backing-service versions are pinned *for running* the system (not just\n  building it): container base images (`Dockerfile`\u002F`Containerfile`,\n  `docker-compose*` build contexts), CI runner images \u002F `setup-*` versions,\n  `engines`\u002F`.nvmrc`\u002F`.tool-versions`\u002F`runtime.txt`, serverless\u002Flambda runtimes,\n  and stateful data-store image tags (DB\u002Fcache\u002Fbroker\u002Fsearch). Cite each with\n  file+line. This surface is what a later platform\u002Fruntime bump must move in\n  lockstep — flag any drift between build-runtime and run-runtime here so it's\n  visible before a modernization plan is written.\n- **EOL \u002F dead-dependency scan** — call out frameworks, runtimes, base images,\n  and libraries that are end-of-life, unmaintained, or removed in a likely target\n  major (e.g. a framework whose next major renames namespaces or drops a\n  component family). Mark each `[INFERRED]`\u002F`[UNVERIFIED]` as appropriate. This is\n  the raw material Modernization mode's feasibility spike and hazard red-team\n  build on.\n- Data\u002Fstorage layers, APIs, plugins\u002Fextensions, background jobs, CI\u002FCD, testing.\n\n#### Part 2 — Context & ecosystem\n- Local checkout identity table (remote, branch, HEAD commit, version, license).\n- Repo-specific agent\u002Fcontributor docs present, and what rules they encode.\n- Developer gotchas (test watch-mode defaults, slow builds, codegen-must-commit,\n  pre-commit hooks) — each cited.\n- How this project relates to its broader ecosystem or sibling services, *as\n  visible from disk* (build tags, optional linked repos, separately-deployable\n  components). Don't import remote ecosystem trivia.\n\n#### Part 3 — Architectural blueprint\n- Tech-stack summary (can reference the Part 1 table).\n- C4-style diagrams as Mermaid: Level 1 system context, Level 2 containers,\n  Level 3 a representative request\u002Fcomponent lifecycle.\n- Layering and dependency rules (what may depend on what, and what enforces it).\n- Cross-cutting concerns table: auth, config, logging, metrics\u002Ftracing, secrets,\n  error handling, feature flags — each with its location and evidence.\n- Inferred Architectural Decision Records (reconstructed from code + docs).\n- Governance & enforcement mechanisms (CI gates, codegen verification,\n  CODEOWNERS, review gates, compatibility rules).\n- \"How to add a feature\" guide plus common pitfalls.\n\n#### Subsystem deep-dives\nIdentify the 2-3 most complex or architecturally significant subsystems — the\nparts a new engineer would most struggle with, such as an evaluation\u002Fscheduling\nengine, a plugin loader pipeline, a state machine, or a rendering\u002Fmigration\nframework. For each, add a dedicated subsection covering its internal structure,\nlifecycle or state machine, key types, and data flow, with local file+line\ncitations and a small Mermaid diagram where it clarifies the flow. This is what\nseparates a useful onboarding doc from a directory listing — spend real effort\nhere.\n\n#### Confidence assessment\nA table of the major claim areas rated **High \u002F Inferred \u002F Unverified**, so a\nreader knows exactly which parts to trust outright and which to double-check.\n\n#### Footnotes — local file citations\nA list of the key local files the document relies on, each with a one-line note\non what it establishes.\n\n### Conventions that make the document trustworthy\n\nThese are the habits that distinguish this skill's output from a generic\noverview. They matter because the document's entire value is that a reader can\nrely on it without re-deriving everything.\n\n- **Cite every non-obvious claim** to a local path, with a line number where it\n  pins something specific (`pkg\u002Fserver\u002Fserver.go#L39-L41`). Relative paths from\n  the repo root keep links clickable.\n- **Mark uncertainty honestly.** Use `[INFERRED]` for something you reasoned to\n  but didn't see stated, and `[UNVERIFIED]` for something you're repeating but\n  didn't confirm (e.g. a build-timing claim from a doc you didn't re-measure).\n  Honest gaps are more useful than false confidence.\n- **Resolve contradictions, don't restate them.** If two sources disagree (say a\n  version literal in code vs. the manifest), go read the code, decide the real\n  answer, and label it `[Resolved contradiction]` with the explanation. Leaving\n  a reader to puzzle over a conflict is a failure mode.\n- **Note compatibility and deploy-cadence rules** the repo enforces — separate\n  FE\u002FBE PRs, bidirectional storage compatibility, additive-only protobuf changes\n  — because these are the rules a newcomer most easily breaks.\n- **Prefer precise counts over vague ones.** \"73 service packages\", \"89 workflow\n  files\" (from a directory listing) reads as verified; \"many services\" reads as a\n  guess.\n\n### Scope control\n\nKeep the document grounded in the checkout. It's easy to drift outward into the\nproject's wider ecosystem (related products, README marketing, satellite repos)\n— resist that unless it's visible on disk, and clearly label anything that comes\nfrom outside the local tree. The reader asked for *this codebase*, documented\nfaithfully.\n\n## Modernization mode\n\nGenerate a complete, actionable modernization plan for a legacy codebase. This\nskill focuses on the forward-looking work — what to modernize, why, in what\norder, and how — but it is **self-sufficient**: it ensures an architecture\ndocument exists first, producing one via Documentation mode when needed.\n\n**Assume dead-by-default.** People reach for modernization precisely because the\nold stack is hard or impossible to upgrade — EOL runtimes, uncompilable native\nmodules, retired package mirrors, abandoned frameworks. So this skill does **not**\nassume you can resurrect the legacy toolchain and stand up a fully-green CI gate\nbefore touching anything. That \"freeze-then-lift\" approach is the *lucky* case,\nnot the default. Instead the skill runs a **time-boxed feasibility spike**, then\npicks a migration strategy and a **safety strategy** matched to how alive the\nsystem actually is. On a truly dead app, building a green legacy gate *is itself\na modernization project* — a circular trap this skill is designed to avoid.\n\nThree ideas drive the whole plan and are introduced below: the **Testability\nMilestone** (when — per component — the system can actually build, run, and pass\na test again), the **safety ladder** (the highest rung of regression safety\nyou can actually reach, with a downgrade treated as a blessed outcome, not a\nfailure), and the **CI Milestone** (which phase first stands up CI — and the\nreminder that *enforcing* CI as a required check is a manual human step, not\nsomething the agent can do).\n\n### Prerequisites\n\nThis skill needs an understanding of the system's architecture before it can\nplan. Resolve that as follows:\n\n1. If an architecture document already exists — produced by **Documentation mode**\n   above, or a README \u002F ARCHITECTURE.md the user points to, or enough\n   prior conversation context — use it and skip to the workflow below.\n2. **If none exists, run the Documentation mode workflow above first** to\n   generate a cited architecture document, then continue **straight through**\n   to Phase 1 below in the same pass. Do not stop to ask the user to run it\n   separately, and do not pause for review between the two documents.\n\nThe result is two artifacts: the architecture document (the audited evidence\nbase) and this modernization plan (the forward-looking action set).\n\n**Before planning, confirm a Commands & Verification Inventory exists.** Exit\ncriteria are only worth anything if they are *runnable*, so the plan must be able\nto cite the project's canonical build \u002F run \u002F test \u002F lint \u002F typecheck \u002F e2e \u002F\ncontract commands and CI gate(s). Documentation mode produces this\ninventory in Part 1; if you're working from a README or prior context that lacks\nit, detect and record those commands yourself (per-ecosystem — npm\u002Fyarn\u002Fpnpm,\n`make`, `just`, `cargo`, `go`, `poetry`\u002F`tox`\u002F`nox`, `gradle`\u002F`mvn`, etc.) before\nwriting exit criteria. Never invent a command you haven't verified against the\ntask runner \u002F manifests \u002F CI config.\n\n### Workflow\n\n#### Phase 1: Assess Current State (from existing docs)\n\nRead the architecture document and extract:\n\n1. **Tech stack inventory** — languages, frameworks, runtimes, dependencies with\n   versions where visible\n2. **Feature\u002Fdomain map** — the major functional areas of the system\n3. **Pain points already identified** — tech debt, concerns, deprecated deps,\n   architectural violations noted in the existing docs\n4. **Deployment and infrastructure** — how it runs today\n\nDo NOT re-read every source file. Trust the architecture doc. Only open specific\nfiles if a modernization question requires verifying a detail (e.g., \"is this\ndependency actually used or just declared?\").\n\n#### Phase 2: Feasibility Spike, Strategy Fork & Safety Ladder\n\nThis is the pivot of the whole plan. **Do it before recommending a target\narchitecture or writing any phases.** Its job is to answer, quickly and honestly:\n*how alive is this system, what migration shape fits, and how much regression\nsafety can we actually achieve?*\n\n##### 2a. Run a time-boxed feasibility spike\n\nPut a **hard time box** on it (e.g. one day). The spike's question is **NOT \"can\nwe make CI green?\"** — it is **\"can we get this to run even *once* to capture its\nbehavior?\"** Probe, per component \u002F deployable unit:\n\n- Does it **install** its dependencies today (ideally **from a committed\n  lockfile without hand-patching**)?\n- Do **native\u002Fbuild steps** succeed on a **currently supported** toolchain?\n- Does it **boot \u002F start**?\n- Can the **test runner execute at all**, and does **≥1 meaningful test pass**?\n\nRecord what you actually observed — including partial success (common in\nmonorepos: one service installs and tests green while another can't compile). Do\n**not** sink two sprints resurrecting a corpse to discover it's unresurrectable.\nWhen the time box expires, decide with the evidence you have.\n\n##### 2b. Locate the Testability Milestone (per component)\n\n**\"Testable\" is not a precondition you can satisfy on a dead app — for a dead app\nit is an *output* of modernization, not an input.** So every plan must name, up\nfront, its **Testability Milestone**: the specific phase at which the system\n(or a given component) first satisfies **all four** conditions at once:\n\n1. Runs on a **supported** (non-EOL) runtime.\n2. Dependencies install **from a lockfile without hand-patching**.\n3. Native \u002F build steps **succeed on the current toolchain**.\n4. The **test runner executes and ≥1 meaningful test passes in CI**.\n\nAssess this **per component** — as the reference Nylas run showed, a near-modern\ncloud service can cross the line immediately while a legacy Electron client\ndoesn't cross it until several phases later. **This milestone is the single most\nimportant marker in the plan.** State where it lands for each component, out loud.\n\n##### 2c. Label every phase pre- or post-testability\n\nThe Testability Milestone splits the effort into two regimes with **different\nsafety rules**:\n\n- **Pre-testability (\"dark\") regime:** the component can't be trusted to run.\n  Safety comes from **non-test** sources (see the safety ladder below).\n  **Requiring a CI test gate here is a category error** — you're demanding green\n  tests from something that isn't alive yet.\n- **Post-testability (\"lit\") regime:** it builds and runs on a live, supported\n  stack. *Now* real CI, characterization, and e2e are achievable and worth the\n  investment. The classic green-gate belongs **here**.\n\n**Rule: never require an automated test gate on a component before that component\ncrosses its own testability line.**\n\n##### 2d. Choose the migration strategy — the A\u002FB fork\n\nThe spike decides which of two shapes fits (this is a per-component call in a\nmonorepo):\n\n- **(A) Freeze-then-lift.** Net the old app *as-is*, then upgrade under the net.\n  Requires the old app to be **resurrectable at acceptable cost** — i.e. it\n  *almost* runs. This is the traditional \"characterization tests before you\n  change anything\" path. **Opt-in, not the default.**\n- **(B) Beachhead-then-expand (walking skeleton).** Don't net the corpse. Drive\n  the **thinnest possible end-to-end slice onto the modern stack** until it\n  builds, boots, and tests; then strangle the rest in, writing tests **on the new\n  stack** as you go. **This is the default for dead apps.** In strategy B, the\n  first phase is *\"reach the Testability Milestone with the smallest slice,\"* not\n  *\"freeze the whole legacy toolchain.\"*\n\nIf a component **can't be built or run at all**, characterization tests on the\n*old* stack are impossible by definition — invert the approach: **stop trying to\nnet the corpse and build the net on the *target* stack incrementally**, using the\nold code\u002Foutput as the reference oracle.\n\n##### 2e. Pick the highest achievable rung on the safety ladder\n\nRegression safety is a ladder, not a binary. Choose the **highest rung you can\nactually reach** per component; **a downgrade to a lower rung is a blessed,\nfirst-class outcome — not a failure — provided the residual risk is named.**\n\n- **L4 — Full automated gate:** green lint + unit + characterization + e2e in CI.\n- **L3 — Partial gate:** some suites green + lockfile + CI on the achievable\n  subset; the rest **quarantined** with a named list.\n- **L2 — Characterization \u002F golden-master only:** can't run in CI, but capture\n  I\u002FO snapshots \u002F behavioral diffs (manual is acceptable).\n- **L1 — Reversibility-based:** no runnable tests; safety comes from small\n  reversible steps, strangler \u002F parallel-run, a smoke checklist, and review.\n- **L0 — No net possible:** treat as a spec-driven rewrite (old code = the spec)\n  or archive.\n\n**Safety is not only tests.** There are at least five sources, and on dead apps\n2–4 often outweigh 1:\n\n1. **Tests** (characterization \u002F unit \u002F e2e) — strongest, often unachievable on\n   dead apps.\n2. **Reversibility** — tiny commits, branch-per-change, trivial rollback.\n3. **Isolation** — feature flags, strangler-fig, run old + new in parallel and\n   **diff outputs**.\n4. **The running old system as an oracle** — record\u002Freplay real I\u002FO to\n   characterize behavior without a test harness.\n5. **Human review + domain knowledge.**\n\n**Anchor safety at the behavioral *seams*, not the unit.** The durable,\nstack-agnostic contracts of any app are its externally observable behaviors:\nHTTP endpoints, DB schema\u002Fqueries, file\u002Fwire formats, CLI output, protocols. Pin\n*those* as golden-master \u002F approval snapshots — **they survive the rewrite; unit\ntests on dead legacy code get deleted the moment you replace the module.** Get an\n**oracle**, ranked by what's available:\n\n- **Best — it runs *somewhere*** (prod, a VM, an old container, even read-only),\n  **and you're allowed to use it**: record real I\u002FO and replay it against the new\n  code. One successful capture beats a permanent green legacy CI. *(Do not assume\n  this rung is always available — a faithful third-party reimplementation or a\n  resurrected legacy binary may be off-limits by policy, licensing, or an\n  explicit decision to build \"with only what we have.\" If so, skip to the\n  self-frozen rung.)*\n- **Fallback — it doesn't run at all:** the old **source is the spec**;\n  supplement with prod logs, DB dumps, docs, tickets, and accept that\n  characterization tests get written **against the new implementation** to lock\n  it once verified correct.\n- **Self-frozen golden master — no external reference exists or is permitted:**\n  when nothing trustworthy runs *and* you may not borrow an external oracle, the\n  **modernized component records its *own* golden master the moment it first runs**\n  (at its Testability Milestone), and every later phase diffs against that frozen\n  snapshot. This is a real, usable rung — but **name its residual risk out loud**:\n  it guarantees the *self-consistency of later refactors*, **not** the correctness\n  of the first boot (the snapshot is only as correct as the run that produced it).\n  Pair it with human review \u002F spec cross-checks to bless that first run.\n\n##### 2f. Feed an economic\u002Foracle triage into the choice\n\nWeigh **regression cost** when picking a rung: Is the app **in production**? Does\nit have **real users**? Is the **old system still runnable** as a reference? An\nabandoned app with zero users has near-zero regression cost — an expensive gate\nthere is **over-engineering**. A production system with users justifies a higher\nrung and a real oracle.\n\n##### 2g. Locate the CI Milestone (name the phase that stands up CI)\n\nJust as the Testability Milestone names *when a component can first run and be\ntested*, the **CI Milestone** names *when continuous integration is first stood\nup* — and it must be **stated out loud in the roadmap, not buried in a phase\nbody.** A common failure of modernization plans is leaving the reader unable to\ntell which phase introduces CI; name it explicitly.\n\n**Rule: CI is stood up in the *first lit phase* — at or immediately after the\ncomponent crosses its Testability Milestone — never before.** CI cannot be green\non a component that cannot yet build\u002Frun, so wiring a CI *gate* during the dark\nregime is the same category error as demanding a test gate there. (Trivial\nscaffolding — a lint-only or build-only workflow — may appear earlier, but the\nauthoritative test gate lands at the CI Milestone.)\n\n**CI is two distinct steps, and the second is human-only** — call both out:\n1. **Author the CI workflow file** (e.g. `.github\u002Fworkflows\u002F*.yml`, `.gitlab-ci.yml`,\n   Azure Pipelines) that runs the gate. **An agent can do this.**\n2. **Make that workflow an *enforced* gate** — a **required status check \u002F\n   branch-protection rule \u002F merge-request approval rule**. This is a manual\n   platform-UI \u002F admin step (GitHub → Settings → Branches; GitLab protected\n   branches + MR settings; etc.) that **an agent cannot perform.** Until a human\n   configures it, CI *runs* on PRs but does **not** *block* merges.\n\nBecause step 2 is outside the agent's reach, **every plan that stands up CI must\nemit it as an explicit user action item** (in the phase's exit criteria and in\n§9 Open questions \u002F decisions needed from stakeholders), so the reader knows the\ngate is not self-enforcing until they turn it on.\n\n**Output of Phase 2:** for each component — the spike result, the chosen strategy\n(A or B), the located Testability Milestone, the pre\u002Fpost label, and the target\nsafety-ladder rung with any residual risk named — **plus the plan-wide CI\nMilestone** (which phase stands up CI) and the reminder that enforcing it is a\nmanual human step. Everything downstream depends on these.\n\n#### Phase 2.5: Red-team every phase against the hazard catalog (mandatory)\n\nThe strategic scaffolding above (testability, safety ladder, CI milestone) is\nnecessary but **not sufficient**. Modernization plans also fail on *tactical,\necosystem-predictable* hazards — an incomplete quarantine set, a forgotten\nnamespace codemod, a runtime bump that leaves the base images behind, a stateful\ndata-store major treated as an image bump, an edge rewrite that drops the\nanonymous route class. These are so recurring that they have their own catalog:\n**`references\u002Fmigration-hazards.md`** (H1–H8).\n\n**Rule: before any phase is implemented, red-team its plan against every hazard\nin `references\u002Fmigration-hazards.md`.** For each hazard, ask \"does this phase\ntrigger it?\", run the hazard's detection probe against the real repo, and fold\nits plan action into the phase's tasks\u002Fexit criteria **before** writing code. A\nhazard caught in planning is a task; caught in review it's rework; caught in prod\nit's an incident. Record hazards you checked and **cleared**, not just the ones\nthat fired — a silent skip is indistinguishable from a miss.\n\nThis is the institutionalized form of an independent-critic pass. Do it yourself\nby walking the catalog, and — where an independent second opinion is available\n(e.g. a rubber-duck \u002F critique agent) — use it: on the reference PiggyMetrics run\nsuch a pass caught a **blocking plan gap in every single phase**, and each gap\nwas an instance of an H1–H8 class. Bake the outcome into each phase's\n\"Decisions made\" and exit criteria so the executing agent inherits the cleared\nchecklist rather than re-discovering the hazard.\n\n#### Phase 3: Recommend Target Architecture\n\n**Decision framework — always evaluate in this order:**\n\nFor each component\u002Fdependency, work through these levels from least-disruptive to\nmost-disruptive. Stop at the first level that solves the problem:\n\n1. **Upgrade in place** — Can you bump the major version and fix breakages?\n   (e.g., Node 14→22, Python 2→3, React 16→19, Rails 5→7). This is the default\n   answer. Only reject it if the upgrade path is officially unsupported, the\n   breaking changes are so extensive they exceed rewrite cost, or the framework\n   itself is abandoned\u002FEOL.\n\n2. **Swap the dependency** — If the specific library is dead but the pattern is\n   fine, can you swap to a maintained alternative with the same interface shape?\n   (e.g., Moment.js → date-fns, Request → got\u002Ffetch, CoffeeScript → TypeScript\n   with decaffeinate). Prefer drop-in or mechanical migration tools when they\n   exist.\n\n3. **Wrap\u002Fadapt (Strangler Fig)** — If the component's interface is sound but\n   internals are unmaintainable, can you put a clean interface in front and\n   incrementally replace internals behind it? This works when coupling is\n   manageable and the system can run with old and new coexisting.\n\n4. **Rewrite** — Only when: the framework is abandoned with no upgrade path, the\n   architecture fundamentally cannot support required new capabilities (e.g.,\n   synchronous-only design that must become real-time), or honest estimation shows\n   upgrade cost exceeds rewrite cost. Require explicit justification for every\n   rewrite recommendation — \"it's old\" is not sufficient.\n\n5. **Remove** — Dead code, features with zero usage, deprecated capabilities\n   superseded by other systems. Verify usage claims before recommending removal.\n\n**Bias toward conservatism.** The cheapest migration is the one you don't do.\nEvery level of disruption adds risk, timeline, and cost. A working system on an\nolder framework is better than a half-finished rewrite on a new one.\n\n**Mechanical-migration riders (apply whenever a recommendation is an upgrade,\nswap, or removal).** These are the parts of a target-architecture decision that\nfirst-draft plans routinely drop; each maps to a hazard class in\n`references\u002Fmigration-hazards.md`:\n\n- **Transitive-quarantine completeness (H1).** When removing\u002Fcutting over a whole\n  dependency family, grep the dead artifact across **all** manifests and list the\n  *full* set of dependents that must move or be quarantined — not the subset you\n  first thought of. State the post-cutover build target explicitly.\n- **Framework-major codemods (H2).** A **major** bump carries mechanical breaking\n  changes independent of your logic — namespace renames, removed deprecated APIs,\n  a changed **test engine**, changed config keys. Enumerate each as its own task\n  and prefer the ecosystem's automated **recipe\u002Fcodemod tool** (OpenRewrite,\n  jscodeshift\u002Freact-codemod, `2to3`\u002F`pyupgrade`, etc.) over hand-editing on large\n  trees. Don't forget the test-framework migration — it is the most-forgotten one.\n- **Runtime↔deployment lockstep (H3).** If a recommendation bumps the\n  language\u002Fruntime **major**, every place the runtime is pinned for *running* the\n  app — base images, `docker-compose` build contexts, CI runner images,\n  `engines`\u002F`.nvmrc`\u002F`.tool-versions`, serverless runtimes — must move in the\n  **same phase**. Build-runtime and run-runtime must never drift across a phase\n  boundary, or the app builds green and then fails to run.\n\nProduce a **Target Architecture** section that includes:\n\n- **Recommended tech stack** with rationale for each choice (framework, language,\n  runtime, database, infrastructure)\n- **Architectural pattern** recommendation (monolith → modular monolith →\n  services, event-driven, serverless, etc.) with justification\n- **What stays vs. what goes** — explicitly categorize each major component using\n  the decision framework above:\n  - ✅ Keep as-is (still modern\u002Fadequate)\n  - ⬆️ Upgrade in place (bump version, fix breakages)\n  - 🔀 Swap dependency (replace dead library with maintained equivalent)\n  - 🔄 Wrap\u002Fadapt (add an interface layer, incrementally replace internals)\n  - 🔁 Rewrite (fundamentally incompatible — justification required)\n  - 🗑️ Remove (dead code, deprecated features, superseded)\n\nFor each recommendation, write an inline ADR:\n\n```markdown\n#### ADR: [Decision Title]\n- **Context:** [Why this decision is needed]\n- **Decision:** [What we chose and which decision framework level it falls under]\n- **Alternatives considered:** [What else was evaluated and why it lost]\n- **Consequences:** [Tradeoffs accepted]\n```\n\n#### Phase 4: Per-Feature Migration Analysis\n\nFor each major feature\u002Fdomain identified in the architecture doc, produce a\nsection covering:\n\n1. **Current implementation** — one paragraph summary with file references\n2. **Migration strategy** — the A\u002FB choice from Phase 2 for this component\n   (Freeze-then-lift vs. Beachhead\u002Fwalking-skeleton), plus the tactic: Strangler\n   Fig, Big Bang rewrite, Lift & Shift, Incremental Refactor, or Leave In Place\n3. **Testability status** — where this component's **Testability Milestone**\n   lands, and its **safety-ladder rung** (L0–L4) with residual risk named\n4. **Dependencies and coupling** — what else breaks or must move with it\n5. **Effort estimate** — T-shirt size (XS\u002FS\u002FM\u002FL\u002FXL) with justification\n6. **Risk assessment** — what can go wrong, data migration concerns, user impact\n7. **Acceptance criteria** — how you know the migration succeeded (expressed\n   against the chosen oracle\u002Fseam contracts, not against a not-yet-alive test\n   suite)\n\n#### Phase 5: Phased Implementation Plan\n\nProduce an ordered, phased plan. Each phase should be independently deployable\n(no half-migrated states that can't run in production).\n\n**Phase gating is regime-aware (applies to every phase).** State this rule at the\ntop of the phased plan and honor it in every phase's exit criteria. A phase is\n**not complete** until its Verification & Exit Criteria pass. Those criteria must\nbe (a) **objectively verifiable**; (b) **actually executed and recorded** before\nthe next phase starts; and (c) **gated** — do not advance to phase N+1 until\nphase N's criteria are demonstrably met. **But which criteria are valid depends\non the component's regime (Phase 2c):**\n\n- **Post-testability (\"lit\") phases:** exit criteria are runnable commands \u002F green\n  CI — **green CI on the phase's branch\u002FPR is the authoritative signal.**\n- **Pre-testability (\"dark\") phases:** the component isn't alive yet, so a green\n  CI test gate is a **category error**. Exit criteria come from the achievable\n  safety-ladder rung instead — captured seam\u002Foracle snapshots, reversibility\n  scaffolding proven present, a passed smoke checklist, recorded review. Do **not**\n  block a dark-regime phase on a test suite that can't run yet.\n\nReport to the user any phase whose pass\u002Ffail is unknown rather than assuming it\npassed.\n\n**The first phase establishes maximum *achievable* safety — not a fixed \"green\nlegacy gate.\"** Do not hard-code \"resurrect everything and make CI green.\" Shape\nthe first phase from the Phase 2 outputs, per component:\n\n- **Strategy A (Freeze-then-lift), component is resurrectable:** the first phase\n  *is* the classic Safety Net & Baseline — purely additive, no behavior change:\n  - **Characterization \u002F golden \u002F contract tests** at the **seams** that pin\n    current observable behavior (protocol traces, API snapshots, output goldens).\n  - **CI + lint + formatter** wired up and green (an authoritative gate for later\n    lit-regime phases).\n  - **Pinned dependencies \u002F committed lockfile** and a recorded known-good\n    baseline (versions, toolchain, how it builds and runs today).\n  - **\"Net proven to fail.\"** Deliberately mutate the code (e.g., change one\n    protocol code or return value), confirm the new tests go **red**, then\n    revert. A safety net that never fails is proof of nothing — prove it has\n    teeth.\n- **Strategy B (Beachhead\u002Fwalking-skeleton), component is dead:** the first phase\n  is **\"reach the Testability Milestone with the smallest slice\"** — drive the\n  thinnest end-to-end path onto the modern stack until it builds, boots, and runs\n  ≥1 real test green, capturing seam\u002Foracle contracts from the old system to\n  validate against. **Do not try to net the corpse.** Its exit criterion is the\n  achievable safety-ladder rung with residual risk named — a **blessed downgrade\n  is not a failure.**\n\nOnly after the first phase's criteria are met (at whatever rung) do the\nsubsequent infrastructure and feature phases begin.\n\nStructure each phase as:\n\n```markdown\n### Phase N: [Name] (T-shirt size: M)\n\n**Goal:** [One sentence]\n**Regime:** [pre-testability (\"dark\") | post-testability (\"lit\")] — per component\n**Safety rung:** [L0–L4, with residual risk named if below L4]\n**Prerequisites:** [Which phases must complete first]\n**Duration estimate:** [Relative, not calendar — e.g., \"2-4 sprints\"]\n\n#### Tasks\n| ID | Task | Component | Blocked by |\n|----|------|-----------|------------|\n| N.1 | ... | ... | — |\n| N.2 | ... | ... | N.1 |\n\n#### Risks & Mitigations\n- **Risk:** ... → **Mitigation:** ...\n\n#### Decisions made\n- [Every sub-decision this phase depends on, resolved and documented here so the\n  phase can be implemented without further user input. State \"dropped\" vs\n  \"deferred\" explicitly for anything cut.]\n\n#### Verification & Exit Criteria (Definition of Done)\n- [ ] [Regime-appropriate criterion. For LIT phases: a runnable command \u002F green\n      CI check, citing the actual command from the Commands & Verification\n      Inventory. For DARK phases: the achievable safety-ladder rung's evidence —\n      captured seam\u002Foracle snapshots, reversibility proven, smoke checklist\n      passed — NOT a green test suite the component can't yet run.]\n- [ ] [Include a parity\u002Fcharacterization check against the chosen oracle whenever\n      the change is meant to preserve behavior.]\n- [ ] [If purely additive, assert it: \"no behavior\u002Fdependency\u002Flogic changed.\"]\n- [ ] [If exiting below L4, state the residual risk and which later phase closes\n      it (e.g., \"client test gate deferred to the client-migration phase\").]\n```\n\n**Ordering principles:**\n- **Locate the Testability Milestone first**, per component — schedule the\n  smallest slice that reaches it early rather than deferring \"testable\" to the end\n  while demanding a gate at the start.\n- **Never require a component's automated test gate before it crosses its own\n  testability line.**\n- **Name the CI Milestone in the roadmap.** State explicitly which phase stands\n  up CI (the first *lit* phase, at\u002Fafter the Testability Milestone) so the reader\n  never has to guess when CI arrives — and flag that *enforcing* it (required\n  status check \u002F branch protection) is a manual human step, not an agent task.\n- **First-phase safety before behavior change** — establish the highest\n  achievable rung (not necessarily a full green gate) before modifying behavior.\n- Infrastructure and cross-cutting concerns next (auth, config, logging, CI\u002FCD)\n- Highest-risk or highest-value features next (prove the pattern early)\n- Low-risk, low-coupling features last (easy wins to parallelize)\n- Data migrations get their own phase with rollback plans\n\n#### Phase 6: Execution Governance\n\nModernization plans fail in execution, not on paper. Bake in the governance that\nkeeps each phase honest and reversible (generic across any ecosystem):\n\n- **Branch per phase.** Never commit phase work to the default branch. Open one\n  PR per phase; let CI on the PR be the authoritative green signal before merge\n  **for lit-regime phases**. For dark-regime phases, the PR still carries the\n  rung's evidence (captured contracts, smoke results, reversibility scaffolding).\n- **Merge to trunk before the next phase; never stack (H7).** Each phase branch\n  is cut **from trunk**, and its PR is **merged to trunk before the next phase\n  starts**. Never base a phase branch or its PR on a *sibling* phase branch — that\n  is how PRs get merged into each other, the trunk silently stalls several phases\n  behind, and later phases are forced into the exact bind where the no-stacking\n  rule has to be broken. Before starting a phase, verify the previous phase is\n  merged to trunk and `git log origin\u002F\u003Ctrunk>..HEAD` is empty at branch creation.\n  **If controlled stacking is genuinely unavoidable, it is allowed only with a\n  required reconciliation PR** that lands the stack onto trunk **and an explicit\n  residual-risk note** — never as a silent default.\n- **Confirm the trunk name; retire legacy defaults.** Pin the repo's real trunk\n  (e.g. `main`) and, if a second default-ish branch exists (`master`), mark it\n  \"history only — do not target\" so phase work never lands on the wrong branch.\n- **The gate matches the regime.** Lit phases advance on green CI; dark phases\n  advance on the achievable safety-ladder rung with residual risk named — not on\n  a \"looks done\" judgement, and not on a test suite that can't run yet.\n- **Stand up CI at the CI Milestone, and hand off enforcement to a human.**\n  Name the phase that introduces CI (the first lit phase). Distinguish the two\n  steps: authoring the workflow file is agent-doable; making it an **enforced\n  required status check \u002F branch-protection (or MR-approval) rule is a manual\n  platform-UI step the agent cannot perform.** Until a human configures it, CI\n  *runs* but does not *block* merges — so record \"enable branch protection \u002F\n  required checks\" as an explicit user action item (in the CI phase's exit\n  criteria and in §9 stakeholder decisions), never as a completed agent task.\n- **Interface-preserving & independently deployable.** Each phase leaves the\n  system runnable, so rollback = redeploy the previous version. Prefer\n  interface-preserving rewrites (wrap internals behind a stable interface) and\n  prove equivalence with the seam\u002Foracle contracts (golden\u002Fcharacterization\n  tests where they exist).\n- **Living plan.** Update `MODERNIZATION_PLAN.md` status markers as each phase's\n  exit criteria are met — ✅ complete \u002F ⏭️ descoped \u002F 🗑️ dropped — record the\n  decisions made during implementation, and **update the safety-ladder rung \u002F\n  residual-risk register** as components cross their testability lines.\n- **Keep the executable docs alive too (H8).** The living-plan discipline is not\n  only the plan file. Any phase that changes **topology** — module\u002Freactor\n  membership, removed services, renamed branches, changed commands, new\u002Fremoved\n  endpoints — must update `.github\u002Fcopilot-instructions.md`, the `README`, and any\n  module\u002Ftopology list **in the same PR**. Treat those doc updates as part of the\n  phase's Definition of Done, not a follow-up — a stale \"quarantined module\" list\n  or a hard-coded old-branch link actively misleads the next agent\u002Fhuman.\n- **Red-team each phase before implementing it (Phase 2.5).** Walk the phase plan\n  against `references\u002Fmigration-hazards.md` (H1–H8) and fold the fixes into tasks\n  and exit criteria before writing code. Record the cleared checklist in the\n  phase's \"Decisions made\".\n- **Emit editable instructions.** Produce a `.github\u002Fcopilot-instructions.md`\n  (create the `.github\u002F` directory if needed) from the template at\n  `references\u002Fcopilot-instructions.template.md` — a commands table plus the\n  regime-aware phase-gate and branch\u002FPR rules — so the executing agent\u002Fhuman has\n  the canonical commands and gates in the location GitHub Copilot auto-loads. The\n  user edits it to their own gates. If a `.github\u002Fcopilot-instructions.md` already\n  exists, do not overwrite it — merge the commands\u002Fgating\u002Fbranch sections in, or\n  write the generated file alongside as\n  `.github\u002Fcopilot-instructions.modernization.md` and tell the user to merge.\n\n#### Phase 7: Migration Safety Net\n\nDocument the operational guardrails needed:\n\n- **Feature flags** — what gets flagged and how old\u002Fnew coexist\n- **Data migration strategy** — schema changes, backfills, dual-write periods.\n  For a **stateful data-store major upgrade** with persisted volumes (H5), an\n  engine image\u002Ftag bump is **not** a migration: pick and document one path —\n  a sequential\u002Ffeature-compatibility-version upgrade with steps + rollback, **or**\n  an explicit **destructive reset** (drop volumes, re-seed) when the data is\n  ephemeral\u002Fdemo — stated as a deliberate decision, with the prior-major image\n  retained for rollback. (e.g. Mongo 3→7 over an existing `\u002Fdata\u002Fdb` volume needs\n  `down -v` + re-seed for a demo, or a staged FCV upgrade for real data.)\n- **Rollback plan** — per phase, how to revert if something fails\n- **Transitional-insecure-state register (H6)** — every deliberately-weak state\n  introduced to keep the system runnable mid-migration (permit-all shims, CSRF\n  disabled, an open endpoint, a placeholder secret) listed with: why it's needed,\n  the phase that **closes** it, the residual risk, and a by-design-until-phase-N\n  note for reviewers. Scope each weakening as tightly as possible (e.g. a\n  permit-all chain should still explicitly disable form-login\u002FHTTP-Basic).\n  Pre-declaring these converts recurring scanner\u002Freviewer churn into a tracked\n  decision.\n- **Oracle & seam contracts** — which running instance \u002F recorded I\u002FO \u002F golden\n  snapshots (or a **self-frozen golden master**, when no external reference is\n  available or permitted) serve as the behavioral reference, and how new work is\n  diffed against them\n- **Testing strategy** — what new test coverage is needed (built on the *target*\n  stack as components cross their testability line), and what stays quarantined\n- **Observability** — metrics\u002Falerts that prove the new system matches the old\n\n### Output Structure\n\nProduce a primary Markdown file named `MODERNIZATION_PLAN.md` with:\n\n1. Executive summary (one paragraph: what, why, rough scope)\n2. Current state assessment (from architecture doc)\n3. **Feasibility spike result & strategy** — per component: spike findings, the\n   A\u002FB migration strategy, the located **Testability Milestone**, the target\n   **safety-ladder rung**, and a **residual-risk register** for anything below L4;\n   plus the plan-wide **CI Milestone** (which phase stands up CI) with a note that\n   *enforcing* it is a manual human step\n4. Target architecture with ADRs\n5. Per-feature migration analysis (with testability status + safety rung)\n6. Phased implementation plan — first phase establishes the highest *achievable*\n   safety rung (not a fixed green legacy gate); every phase is labeled\n   pre\u002Fpost-testability and carries regime-appropriate, gated exit criteria; the\n   **CI Milestone phase is named explicitly** and lists \"enable branch protection\n   \u002F required status checks\" as a manual user action\n7. Execution governance (branch-per-phase, regime-aware gate, living-plan status)\n8. Migration safety net (oracle & seam contracts, flags, rollback, observability)\n9. Open questions \u002F decisions needed from stakeholders — including any manual\n   platform-configuration handoffs the agent cannot perform (e.g. enabling\n   required status checks \u002F branch protection to make CI an enforced gate)\n\nAlso emit a companion **`.github\u002Fcopilot-instructions.md`** (the path GitHub\nCopilot auto-loads; create `.github\u002F` if absent) from\n`references\u002Fcopilot-instructions.template.md`, populated with the project's\ncanonical commands and phase-gating \u002F branch rules, for whoever executes the\nplan to edit and adopt. Never overwrite an existing\n`.github\u002Fcopilot-instructions.md` — merge into it or write a sibling\n`.github\u002Fcopilot-instructions.modernization.md` and flag it for the user.\n\n### Conventions\n\n- **Cite the architecture doc** when referencing current state rather than\n  restating everything. Keep this document forward-looking.\n- **Be opinionated.** Make concrete recommendations, not \"you could do A or B.\"\n  State what you'd pick and why. The user can override.\n- **Scope realistically.** A modernization plan that tries to change everything at\n  once is fiction. Identify what's phase 1 vs. \"future consideration.\"\n- **Resolve every in-phase decision during planning.** A phase plan must carry\n  all the sub-decisions its implementation depends on, already decided and\n  documented (the \"Decisions made\" block), so the phase can be executed without\n  going back to the user. State **\"dropped\" vs \"deferred\"** explicitly for\n  anything cut — they are not the same. Reserve `[DECISION NEEDED]` for genuine\n  *stakeholder\u002Fbusiness* choices (budget, team size, product direction, timeline\n  pressure) that block a phase; drive those to resolution with the user during\n  planning rather than leaving them open in an implementable phase.\n- **Don't gold-plate.** If a component works fine on the old stack and has no\n  maintenance burden, \"leave it alone\" is a valid recommendation.\n- **Assume dead-by-default; make safety adaptive.** Don't demand a fully-green\n  legacy CI gate up front. Run the feasibility spike, pick the highest achievable\n  safety-ladder rung, and treat a **downgrade as a blessed outcome** with residual\n  risk named — never a failure.\n- **Locate testability in time.** Every plan must name its **Testability\n  Milestone** per component and never require a component's automated test gate\n  before that component crosses its own testability line.\n- **Name the CI Milestone, hand enforcement to a human.** State which phase\n  stands up CI (the first lit phase), and make explicit that turning CI into an\n  *enforced* required check \u002F branch-protection rule is a manual platform step\n  the agent cannot do — surface it as a user action item, not a done task.\n- **Net the seams, not the corpse.** Anchor safety at externally observable\n  contracts (protocols, schemas, wire\u002Ffile formats, endpoints) with a ranked\n  oracle (running instance → recorded I\u002FO → code-as-spec → **self-frozen golden\n  master** when no external reference exists or is permitted). Don't sink sprints\n  resurrecting a dead toolchain just to run a test that gets deleted at rewrite.\n- **Keep it generic.** Express commands and gates in terms of *the project's*\n  package manager \u002F test runner \u002F CI — never assume a specific stack.\n- **Red-team every phase before implementing (H1–H8).** Walk each phase plan\n  against `references\u002Fmigration-hazards.md` and fold the fixes into tasks\u002Fexit\n  criteria first — a hazard caught in planning is a task; in review, rework; in\n  prod, an incident. These tactical hazards (incomplete quarantine, framework\n  codemods, runtime\u002Fbase-image lockstep, route-class enumeration, data-store\n  upgrade paths, transitional-insecure-state noise, stacked-PR\u002Ftrunk drift,\n  living-doc drift) are what strategic scaffolding alone keeps missing.\n","# Documentation & Modernization\n\nTwo complementary workflows for a repository the user already has checked out\nlocally, bundled as one skill:\n\n- **Documentation mode** — produce one definitive, cited architecture document\n  from the code on disk. Ideal for onboarding, system-design maps, or as the\n  evidence base for a modernization effort.\n- **Modernization mode** — turn that architecture into a phased, safety-laddered\n  plan to upgrade, migrate, or rewrite a legacy system.\n\n## Mode selection\n\n- If the user wants to **understand, document, map, research, or onboard onto** a\n  codebase, run **Documentation mode**.\n- If the user wants to **modernize, migrate, upgrade, or rewrite** a system, run\n  **Modernization mode**. Modernization mode is self-sufficient: if no\n  architecture document exists yet, it runs the **Documentation mode** workflow\n  first (in the same pass), then continues straight through to the plan.\n\nWhen in doubt, produce the architecture document first — it is the audited\nevidence base both modes rely on.\n\n## Documentation mode\n\nGenerate one definitive, cited architecture document for a repository the user\nalready has checked out locally. The goal is a writeup someone could hand to a\nnew engineer as their onboarding reference — broad enough to cover the whole\nsystem, deep enough on the hard parts to be useful, and trustworthy because\nevery claim traces back to a file on disk.\n\n### Why local-first\n\nReading from the local checkout (not the GitHub API or the web) is the deliberate\n**default**. It is faster, free, avoids rate limits, and — most importantly — it\ndescribes *the exact code in front of you* rather than whatever `main` happens\nto look like remotely. The one tradeoff is that remote-only facts (star counts,\nfull CI run history, sibling repos) aren't visible. That's fine: state those as\nout-of-scope or mark them `[UNVERIFIED]` rather than guessing.\n\nLocal-first is not local-*never*-remote: a web\u002FAPI lookup is a deliberate\n**last-resort fallback**, reserved for a fact that genuinely cannot be determined\nfrom disk and that materially matters to the document. When you do reach for it,\nflag the result clearly (e.g. `[UNVERIFIED]` \u002F sourced-remotely) so the reader\nknows it didn't come from the checkout, and never let it become the easy path\nthat displaces reading the code on disk.\n\n### Workflow\n\n1. **Establish identity first.** Run `git remote -v`, `git branch --show-current`,\n   and `git log -1` so the document is anchored to a specific remote, branch, and\n   commit. A reader must be able to tell which snapshot this describes. Remote\n   URLs can contain embedded credentials (e.g. `https:\u002F\u002F\u003Ctoken>@github.com\u002F...`)\n   — **redact any credentials\u002Ftokens** from the URL before recording it in the\n   document.\n2. **Detect, don't assume.** Read the real manifests (`go.mod`, `package.json`,\n   `Cargo.toml`, `pyproject.toml`, `pom.xml`, etc.), the `Makefile`\u002Ftask runner,\n   CI config, and any repo-specific agent or contributor docs (`AGENTS.md`,\n   `CONTRIBUTING`, `README`, `docs\u002F`). These are the source of truth for the tech\n   stack and commands — prefer them over your prior knowledge of the framework.\n3. **Map breadth, then drill into depth.** First build the whole-repo map (the\n   three lenses below), then pick the 2-3 hardest subsystems and go deep on them.\n4. **Verify as you go.** Open the files you cite. If you reference a line number,\n   you should have actually read that line. Unsupported claims are worse than\n   omissions here — the whole value of this document is that it can be trusted.\n\n### Output structure\n\nProduce a **single Markdown file** with the sections below, in this order. Adapt\nthe headings to the actual project (a CLI tool has no \"frontend\" lens — fold that\nslot into whatever matters for that repo), but keep the three-lens shape and the\nverification discipline.\n\n#### Part 1 — Whole-repo technical deep-dive\n- What the repository is (one paragraph, cited to README).\n- Tech-stack detection table: layer | technology | evidence (file+line).\n- Entry points (backend, frontend, CLI — whatever applies).\n- **Commands & Verification Inventory** — a table of the canonical project\n  commands (`command | purpose | evidence`), verified against the task runner \u002F\n  manifests \u002F CI config, not guessed. Cover build, run\u002Fserve, test (and how to\n  run a single test), lint, format, and — where they exist — typecheck,\n  end-to-end\u002Fsmoke, contract, and any other gate commands, plus the CI\n  workflow(s) that run them and on what trigger. **Also record whether CI is\n  *enforced*** — i.e. whether any workflow is a **required status check \u002F\n  branch-protection rule** that actually blocks merges, versus one that merely\n  runs — since that distinction is a manual, human-configured setting that\n  Modernization mode must surface, not assume. Enforcement usually cannot be\n  determined from the local checkout alone: ask the user, or mark it\n  `[UNVERIFIED]` unless confirmed from an authoritative source (any remote\n  lookup is a flagged last resort, per the local-first rule above). This\n  inventory is the source of\n  truth that downstream planning (Modernization mode) cites so its exit\n  criteria are runnable, not aspirational. Detect these per-ecosystem (npm\u002Fyarn\u002F\n  pnpm, `make`, `just`, `cargo`, `go`, `poetry`\u002F`tox`\u002F`nox`, `gradle`\u002F`maven`,\n  etc.) — do not assume a stack. Mark any command you could not verify\n  `[UNVERIFIED]`.\n- Directory layout for each major area, with a one-line purpose per directory.\n- **Deployment & Runtime Surface** — a table of every place the language\u002Fruntime\n  and backing-service versions are pinned *for running* the system (not just\n  building it): container base images (`Dockerfile`\u002F`Containerfile`,\n  `docker-compose*` build contexts), CI runner images \u002F `setup-*` versions,\n  `engines`\u002F`.nvmrc`\u002F`.tool-versions`\u002F`runtime.txt`, serverless\u002Flambda runtimes,\n  and stateful data-store image tags (DB\u002Fcache\u002Fbroker\u002Fsearch). Cite each with\n  file+line. This surface is what a later platform\u002Fruntime bump must move in\n  lockstep — flag any drift between build-runtime and run-runtime here so it's\n  visible before a modernization plan is written.\n- **EOL \u002F dead-dependency scan** — call out frameworks, runtimes, base images,\n  and libraries that are end-of-life, unmaintained, or removed in a likely target\n  major (e.g. a framework whose next major renames namespaces or drops a\n  component family). Mark each `[INFERRED]`\u002F`[UNVERIFIED]` as appropriate. This is\n  the raw material Modernization mode's feasibility spike and hazard red-team\n  build on.\n- Data\u002Fstorage layers, APIs, plugins\u002Fextensions, background jobs, CI\u002FCD, testing.\n\n#### Part 2 — Context & ecosystem\n- Local checkout identity table (remote, branch, HEAD commit, version, license).\n- Repo-specific agent\u002Fcontributor docs present, and what rules they encode.\n- Developer gotchas (test watch-mode defaults, slow builds, codegen-must-commit,\n  pre-commit hooks) — each cited.\n- How this project relates to its broader ecosystem or sibling services, *as\n  visible from disk* (build tags, optional linked repos, separately-deployable\n  components). Don't import remote ecosystem trivia.\n\n#### Part 3 — Architectural blueprint\n- Tech-stack summary (can reference the Part 1 table).\n- C4-style diagrams as Mermaid: Level 1 system context, Level 2 containers,\n  Level 3 a representative request\u002Fcomponent lifecycle.\n- Layering and dependency rules (what may depend on what, and what enforces it).\n- Cross-cutting concerns table: auth, config, logging, metrics\u002Ftracing, secrets,\n  error handling, feature flags — each with its location and evidence.\n- Inferred Architectural Decision Records (reconstructed from code + docs).\n- Governance & enforcement mechanisms (CI gates, codegen verification,\n  CODEOWNERS, review gates, compatibility rules).\n- \"How to add a feature\" guide plus common pitfalls.\n\n#### Subsystem deep-dives\nIdentify the 2-3 most complex or architecturally significant subsystems — the\nparts a new engineer would most struggle with, such as an evaluation\u002Fscheduling\nengine, a plugin loader pipeline, a state machine, or a rendering\u002Fmigration\nframework. For each, add a dedicated subsection covering its internal structure,\nlifecycle or state machine, key types, and data flow, with local file+line\ncitations and a small Mermaid diagram where it clarifies the flow. This is what\nseparates a useful onboarding doc from a directory listing — spend real effort\nhere.\n\n#### Confidence assessment\nA table of the major claim areas rated **High \u002F Inferred \u002F Unverified**, so a\nreader knows exactly which parts to trust outright and which to double-check.\n\n#### Footnotes — local file citations\nA list of the key local files the document relies on, each with a one-line note\non what it establishes.\n\n### Conventions that make the document trustworthy\n\nThese are the habits that distinguish this skill's output from a generic\noverview. They matter because the document's entire value is that a reader can\nrely on it without re-deriving everything.\n\n- **Cite every non-obvious claim** to a local path, with a line number where it\n  pins something specific (`pkg\u002Fserver\u002Fserver.go#L39-L41`). Relative paths from\n  the repo root keep links clickable.\n- **Mark uncertainty honestly.** Use `[INFERRED]` for something you reasoned to\n  but didn't see stated, and `[UNVERIFIED]` for something you're repeating but\n  didn't confirm (e.g. a build-timing claim from a doc you didn't re-measure).\n  Honest gaps are more useful than false confidence.\n- **Resolve contradictions, don't restate them.** If two sources disagree (say a\n  version literal in code vs. the manifest), go read the code, decide the real\n  answer, and label it `[Resolved contradiction]` with the explanation. Leaving\n  a reader to puzzle over a conflict is a failure mode.\n- **Note compatibility and deploy-cadence rules** the repo enforces — separate\n  FE\u002FBE PRs, bidirectional storage compatibility, additive-only protobuf changes\n  — because these are the rules a newcomer most easily breaks.\n- **Prefer precise counts over vague ones.** \"73 service packages\", \"89 workflow\n  files\" (from a directory listing) reads as verified; \"many services\" reads as a\n  guess.\n\n### Scope control\n\nKeep the document grounded in the checkout. It's easy to drift outward into the\nproject's wider ecosystem (related products, README marketing, satellite repos)\n— resist that unless it's visible on disk, and clearly label anything that comes\nfrom outside the local tree. The reader asked for *this codebase*, documented\nfaithfully.\n\n## Modernization mode\n\nGenerate a complete, actionable modernization plan for a legacy codebase. This\nskill focuses on the forward-looking work — what to modernize, why, in what\norder, and how — but it is **self-sufficient**: it ensures an architecture\ndocument exists first, producing one via Documentation mode when needed.\n\n**Assume dead-by-default.** People reach for modernization precisely because the\nold stack is hard or impossible to upgrade — EOL runtimes, uncompilable native\nmodules, retired package mirrors, abandoned frameworks. So this skill does **not**\nassume you can resurrect the legacy toolchain and stand up a fully-green CI gate\nbefore touching anything. That \"freeze-then-lift\" approach is the *lucky* case,\nnot the default. Instead the skill runs a **time-boxed feasibility spike**, then\npicks a migration strategy and a **safety strategy** matched to how alive the\nsystem actually is. On a truly dead app, building a green legacy gate *is itself\na modernization project* — a circular trap this skill is designed to avoid.\n\nThree ideas drive the whole plan and are introduced below: the **Testability\nMilestone** (when — per component — the system can actually build, run, and pass\na test again), the **safety ladder** (the highest rung of regression safety\nyou can actually reach, with a downgrade treated as a blessed outcome, not a\nfailure), and the **CI Milestone** (which phase first stands up CI — and the\nreminder that *enforcing* CI as a required check is a manual human step, not\nsomething the agent can do).\n\n### Prerequisites\n\nThis skill needs an understanding of the system's architecture before it can\nplan. Resolve that as follows:\n\n1. If an architecture document already exists — produced by **Documentation mode**\n   above, or a README \u002F ARCHITECTURE.md the user points to, or enough\n   prior conversation context — use it and skip to the workflow below.\n2. **If none exists, run the Documentation mode workflow above first** to\n   generate a cited architecture document, then continue **straight through**\n   to Phase 1 below in the same pass. Do not stop to ask the user to run it\n   separately, and do not pause for review between the two documents.\n\nThe result is two artifacts: the architecture document (the audited evidence\nbase) and this modernization plan (the forward-looking action set).\n\n**Before planning, confirm a Commands & Verification Inventory exists.** Exit\ncriteria are only worth anything if they are *runnable*, so the plan must be able\nto cite the project's canonical build \u002F run \u002F test \u002F lint \u002F typecheck \u002F e2e \u002F\ncontract commands and CI gate(s). Documentation mode produces this\ninventory in Part 1; if you're working from a README or prior context that lacks\nit, detect and record those commands yourself (per-ecosystem — npm\u002Fyarn\u002Fpnpm,\n`make`, `just`, `cargo`, `go`, `poetry`\u002F`tox`\u002F`nox`, `gradle`\u002F`mvn`, etc.) before\nwriting exit criteria. Never invent a command you haven't verified against the\ntask runner \u002F manifests \u002F CI config.\n\n### Workflow\n\n#### Phase 1: Assess Current State (from existing docs)\n\nRead the architecture document and extract:\n\n1. **Tech stack inventory** — languages, frameworks, runtimes, dependencies with\n   versions where visible\n2. **Feature\u002Fdomain map** — the major functional areas of the system\n3. **Pain points already identified** — tech debt, concerns, deprecated deps,\n   architectural violations noted in the existing docs\n4. **Deployment and infrastructure** — how it runs today\n\nDo NOT re-read every source file. Trust the architecture doc. Only open specific\nfiles if a modernization question requires verifying a detail (e.g., \"is this\ndependency actually used or just declared?\").\n\n#### Phase 2: Feasibility Spike, Strategy Fork & Safety Ladder\n\nThis is the pivot of the whole plan. **Do it before recommending a target\narchitecture or writing any phases.** Its job is to answer, quickly and honestly:\n*how alive is this system, what migration shape fits, and how much regression\nsafety can we actually achieve?*\n\n##### 2a. Run a time-boxed feasibility spike\n\nPut a **hard time box** on it (e.g. one day). The spike's question is **NOT \"can\nwe make CI green?\"** — it is **\"can we get this to run even *once* to capture its\nbehavior?\"** Probe, per component \u002F deployable unit:\n\n- Does it **install** its dependencies today (ideally **from a committed\n  lockfile without hand-patching**)?\n- Do **native\u002Fbuild steps** succeed on a **currently supported** toolchain?\n- Does it **boot \u002F start**?\n- Can the **test runner execute at all**, and does **≥1 meaningful test pass**?\n\nRecord what you actually observed — including partial success (common in\nmonorepos: one service installs and tests green while another can't compile). Do\n**not** sink two sprints resurrecting a corpse to discover it's unresurrectable.\nWhen the time box expires, decide with the evidence you have.\n\n##### 2b. Locate the Testability Milestone (per component)\n\n**\"Testable\" is not a precondition you can satisfy on a dead app — for a dead app\nit is an *output* of modernization, not an input.** So every plan must name, up\nfront, its **Testability Milestone**: the specific phase at which the system\n(or a given component) first satisfies **all four** conditions at once:\n\n1. Runs on a **supported** (non-EOL) runtime.\n2. Dependencies install **from a lockfile without hand-patching**.\n3. Native \u002F build steps **succeed on the current toolchain**.\n4. The **test runner executes and ≥1 meaningful test passes in CI**.\n\nAssess this **per component** — as the reference Nylas run showed, a near-modern\ncloud service can cross the line immediately while a legacy Electron client\ndoesn't cross it until several phases later. **This milestone is the single most\nimportant marker in the plan.** State where it lands for each component, out loud.\n\n##### 2c. Label every phase pre- or post-testability\n\nThe Testability Milestone splits the effort into two regimes with **different\nsafety rules**:\n\n- **Pre-testability (\"dark\") regime:** the component can't be trusted to run.\n  Safety comes from **non-test** sources (see the safety ladder below).\n  **Requiring a CI test gate here is a category error** — you're demanding green\n  tests from something that isn't alive yet.\n- **Post-testability (\"lit\") regime:** it builds and runs on a live, supported\n  stack. *Now* real CI, characterization, and e2e are achievable and worth the\n  investment. The classic green-gate belongs **here**.\n\n**Rule: never require an automated test gate on a component before that component\ncrosses its own testability line.**\n\n##### 2d. Choose the migration strategy — the A\u002FB fork\n\nThe spike decides which of two shapes fits (this is a per-component call in a\nmonorepo):\n\n- **(A) Freeze-then-lift.** Net the old app *as-is*, then upgrade under the net.\n  Requires the old app to be **resurrectable at acceptable cost** — i.e. it\n  *almost* runs. This is the traditional \"characterization tests before you\n  change anything\" path. **Opt-in, not the default.**\n- **(B) Beachhead-then-expand (walking skeleton).** Don't net the corpse. Drive\n  the **thinnest possible end-to-end slice onto the modern stack** until it\n  builds, boots, and tests; then strangle the rest in, writing tests **on the new\n  stack** as you go. **This is the default for dead apps.** In strategy B, the\n  first phase is *\"reach the Testability Milestone with the smallest slice,\"* not\n  *\"freeze the whole legacy toolchain.\"*\n\nIf a component **can't be built or run at all**, characterization tests on the\n*old* stack are impossible by definition — invert the approach: **stop trying to\nnet the corpse and build the net on the *target* stack incrementally**, using the\nold code\u002Foutput as the reference oracle.\n\n##### 2e. Pick the highest achievable rung on the safety ladder\n\nRegression safety is a ladder, not a binary. Choose the **highest rung you can\nactually reach** per component; **a downgrade to a lower rung is a blessed,\nfirst-class outcome — not a failure — provided the residual risk is named.**\n\n- **L4 — Full automated gate:** green lint + unit + characterization + e2e in CI.\n- **L3 — Partial gate:** some suites green + lockfile + CI on the achievable\n  subset; the rest **quarantined** with a named list.\n- **L2 — Characterization \u002F golden-master only:** can't run in CI, but capture\n  I\u002FO snapshots \u002F behavioral diffs (manual is acceptable).\n- **L1 — Reversibility-based:** no runnable tests; safety comes from small\n  reversible steps, strangler \u002F parallel-run, a smoke checklist, and review.\n- **L0 — No net possible:** treat as a spec-driven rewrite (old code = the spec)\n  or archive.\n\n**Safety is not only tests.** There are at least five sources, and on dead apps\n2–4 often outweigh 1:\n\n1. **Tests** (characterization \u002F unit \u002F e2e) — strongest, often unachievable on\n   dead apps.\n2. **Reversibility** — tiny commits, branch-per-change, trivial rollback.\n3. **Isolation** — feature flags, strangler-fig, run old + new in parallel and\n   **diff outputs**.\n4. **The running old system as an oracle** — record\u002Freplay real I\u002FO to\n   characterize behavior without a test harness.\n5. **Human review + domain knowledge.**\n\n**Anchor safety at the behavioral *seams*, not the unit.** The durable,\nstack-agnostic contracts of any app are its externally observable behaviors:\nHTTP endpoints, DB schema\u002Fqueries, file\u002Fwire formats, CLI output, protocols. Pin\n*those* as golden-master \u002F approval snapshots — **they survive the rewrite; unit\ntests on dead legacy code get deleted the moment you replace the module.** Get an\n**oracle**, ranked by what's available:\n\n- **Best — it runs *somewhere*** (prod, a VM, an old container, even read-only),\n  **and you're allowed to use it**: record real I\u002FO and replay it against the new\n  code. One successful capture beats a permanent green legacy CI. *(Do not assume\n  this rung is always available — a faithful third-party reimplementation or a\n  resurrected legacy binary may be off-limits by policy, licensing, or an\n  explicit decision to build \"with only what we have.\" If so, skip to the\n  self-frozen rung.)*\n- **Fallback — it doesn't run at all:** the old **source is the spec**;\n  supplement with prod logs, DB dumps, docs, tickets, and accept that\n  characterization tests get written **against the new implementation** to lock\n  it once verified correct.\n- **Self-frozen golden master — no external reference exists or is permitted:**\n  when nothing trustworthy runs *and* you may not borrow an external oracle, the\n  **modernized component records its *own* golden master the moment it first runs**\n  (at its Testability Milestone), and every later phase diffs against that frozen\n  snapshot. This is a real, usable rung — but **name its residual risk out loud**:\n  it guarantees the *self-consistency of later refactors*, **not** the correctness\n  of the first boot (the snapshot is only as correct as the run that produced it).\n  Pair it with human review \u002F spec cross-checks to bless that first run.\n\n##### 2f. Feed an economic\u002Foracle triage into the choice\n\nWeigh **regression cost** when picking a rung: Is the app **in production**? Does\nit have **real users**? Is the **old system still runnable** as a reference? An\nabandoned app with zero users has near-zero regression cost — an expensive gate\nthere is **over-engineering**. A production system with users justifies a higher\nrung and a real oracle.\n\n##### 2g. Locate the CI Milestone (name the phase that stands up CI)\n\nJust as the Testability Milestone names *when a component can first run and be\ntested*, the **CI Milestone** names *when continuous integration is first stood\nup* — and it must be **stated out loud in the roadmap, not buried in a phase\nbody.** A common failure of modernization plans is leaving the reader unable to\ntell which phase introduces CI; name it explicitly.\n\n**Rule: CI is stood up in the *first lit phase* — at or immediately after the\ncomponent crosses its Testability Milestone — never before.** CI cannot be green\non a component that cannot yet build\u002Frun, so wiring a CI *gate* during the dark\nregime is the same category error as demanding a test gate there. (Trivial\nscaffolding — a lint-only or build-only workflow — may appear earlier, but the\nauthoritative test gate lands at the CI Milestone.)\n\n**CI is two distinct steps, and the second is human-only** — call both out:\n1. **Author the CI workflow file** (e.g. `.github\u002Fworkflows\u002F*.yml`, `.gitlab-ci.yml`,\n   Azure Pipelines) that runs the gate. **An agent can do this.**\n2. **Make that workflow an *enforced* gate** — a **required status check \u002F\n   branch-protection rule \u002F merge-request approval rule**. This is a manual\n   platform-UI \u002F admin step (GitHub → Settings → Branches; GitLab protected\n   branches + MR settings; etc.) that **an agent cannot perform.** Until a human\n   configures it, CI *runs* on PRs but does **not** *block* merges.\n\nBecause step 2 is outside the agent's reach, **every plan that stands up CI must\nemit it as an explicit user action item** (in the phase's exit criteria and in\n§9 Open questions \u002F decisions needed from stakeholders), so the reader knows the\ngate is not self-enforcing until they turn it on.\n\n**Output of Phase 2:** for each component — the spike result, the chosen strategy\n(A or B), the located Testability Milestone, the pre\u002Fpost label, and the target\nsafety-ladder rung with any residual risk named — **plus the plan-wide CI\nMilestone** (which phase stands up CI) and the reminder that enforcing it is a\nmanual human step. Everything downstream depends on these.\n\n#### Phase 2.5: Red-team every phase against the hazard catalog (mandatory)\n\nThe strategic scaffolding above (testability, safety ladder, CI milestone) is\nnecessary but **not sufficient**. Modernization plans also fail on *tactical,\necosystem-predictable* hazards — an incomplete quarantine set, a forgotten\nnamespace codemod, a runtime bump that leaves the base images behind, a stateful\ndata-store major treated as an image bump, an edge rewrite that drops the\nanonymous route class. These are so recurring that they have their own catalog:\n**`references\u002Fmigration-hazards.md`** (H1–H8).\n\n**Rule: before any phase is implemented, red-team its plan against every hazard\nin `references\u002Fmigration-hazards.md`.** For each hazard, ask \"does this phase\ntrigger it?\", run the hazard's detection probe against the real repo, and fold\nits plan action into the phase's tasks\u002Fexit criteria **before** writing code. A\nhazard caught in planning is a task; caught in review it's rework; caught in prod\nit's an incident. Record hazards you checked and **cleared**, not just the ones\nthat fired — a silent skip is indistinguishable from a miss.\n\nThis is the institutionalized form of an independent-critic pass. Do it yourself\nby walking the catalog, and — where an independent second opinion is available\n(e.g. a rubber-duck \u002F critique agent) — use it: on the reference PiggyMetrics run\nsuch a pass caught a **blocking plan gap in every single phase**, and each gap\nwas an instance of an H1–H8 class. Bake the outcome into each phase's\n\"Decisions made\" and exit criteria so the executing agent inherits the cleared\nchecklist rather than re-discovering the hazard.\n\n#### Phase 3: Recommend Target Architecture\n\n**Decision framework — always evaluate in this order:**\n\nFor each component\u002Fdependency, work through these levels from least-disruptive to\nmost-disruptive. Stop at the first level that solves the problem:\n\n1. **Upgrade in place** — Can you bump the major version and fix breakages?\n   (e.g., Node 14→22, Python 2→3, React 16→19, Rails 5→7). This is the default\n   answer. Only reject it if the upgrade path is officially unsupported, the\n   breaking changes are so extensive they exceed rewrite cost, or the framework\n   itself is abandoned\u002FEOL.\n\n2. **Swap the dependency** — If the specific library is dead but the pattern is\n   fine, can you swap to a maintained alternative with the same interface shape?\n   (e.g., Moment.js → date-fns, Request → got\u002Ffetch, CoffeeScript → TypeScript\n   with decaffeinate). Prefer drop-in or mechanical migration tools when they\n   exist.\n\n3. **Wrap\u002Fadapt (Strangler Fig)** — If the component's interface is sound but\n   internals are unmaintainable, can you put a clean interface in front and\n   incrementally replace internals behind it? This works when coupling is\n   manageable and the system can run with old and new coexisting.\n\n4. **Rewrite** — Only when: the framework is abandoned with no upgrade path, the\n   architecture fundamentally cannot support required new capabilities (e.g.,\n   synchronous-only design that must become real-time), or honest estimation shows\n   upgrade cost exceeds rewrite cost. Require explicit justification for every\n   rewrite recommendation — \"it's old\" is not sufficient.\n\n5. **Remove** — Dead code, features with zero usage, deprecated capabilities\n   superseded by other systems. Verify usage claims before recommending removal.\n\n**Bias toward conservatism.** The cheapest migration is the one you don't do.\nEvery level of disruption adds risk, timeline, and cost. A working system on an\nolder framework is better than a half-finished rewrite on a new one.\n\n**Mechanical-migration riders (apply whenever a recommendation is an upgrade,\nswap, or removal).** These are the parts of a target-architecture decision that\nfirst-draft plans routinely drop; each maps to a hazard class in\n`references\u002Fmigration-hazards.md`:\n\n- **Transitive-quarantine completeness (H1).** When removing\u002Fcutting over a whole\n  dependency family, grep the dead artifact across **all** manifests and list the\n  *full* set of dependents that must move or be quarantined — not the subset you\n  first thought of. State the post-cutover build target explicitly.\n- **Framework-major codemods (H2).** A **major** bump carries mechanical breaking\n  changes independent of your logic — namespace renames, removed deprecated APIs,\n  a changed **test engine**, changed config keys. Enumerate each as its own task\n  and prefer the ecosystem's automated **recipe\u002Fcodemod tool** (OpenRewrite,\n  jscodeshift\u002Freact-codemod, `2to3`\u002F`pyupgrade`, etc.) over hand-editing on large\n  trees. Don't forget the test-framework migration — it is the most-forgotten one.\n- **Runtime↔deployment lockstep (H3).** If a recommendation bumps the\n  language\u002Fruntime **major**, every place the runtime is pinned for *running* the\n  app — base images, `docker-compose` build contexts, CI runner images,\n  `engines`\u002F`.nvmrc`\u002F`.tool-versions`, serverless runtimes — must move in the\n  **same phase**. Build-runtime and run-runtime must never drift across a phase\n  boundary, or the app builds green and then fails to run.\n\nProduce a **Target Architecture** section that includes:\n\n- **Recommended tech stack** with rationale for each choice (framework, language,\n  runtime, database, infrastructure)\n- **Architectural pattern** recommendation (monolith → modular monolith →\n  services, event-driven, serverless, etc.) with justification\n- **What stays vs. what goes** — explicitly categorize each major component using\n  the decision framework above:\n  - ✅ Keep as-is (still modern\u002Fadequate)\n  - ⬆️ Upgrade in place (bump version, fix breakages)\n  - 🔀 Swap dependency (replace dead library with maintained equivalent)\n  - 🔄 Wrap\u002Fadapt (add an interface layer, incrementally replace internals)\n  - 🔁 Rewrite (fundamentally incompatible — justification required)\n  - 🗑️ Remove (dead code, deprecated features, superseded)\n\nFor each recommendation, write an inline ADR:\n\n```markdown\n#### ADR: [Decision Title]\n- **Context:** [Why this decision is needed]\n- **Decision:** [What we chose and which decision framework level it falls under]\n- **Alternatives considered:** [What else was evaluated and why it lost]\n- **Consequences:** [Tradeoffs accepted]\n```\n\n#### Phase 4: Per-Feature Migration Analysis\n\nFor each major feature\u002Fdomain identified in the architecture doc, produce a\nsection covering:\n\n1. **Current implementation** — one paragraph summary with file references\n2. **Migration strategy** — the A\u002FB choice from Phase 2 for this component\n   (Freeze-then-lift vs. Beachhead\u002Fwalking-skeleton), plus the tactic: Strangler\n   Fig, Big Bang rewrite, Lift & Shift, Incremental Refactor, or Leave In Place\n3. **Testability status** — where this component's **Testability Milestone**\n   lands, and its **safety-ladder rung** (L0–L4) with residual risk named\n4. **Dependencies and coupling** — what else breaks or must move with it\n5. **Effort estimate** — T-shirt size (XS\u002FS\u002FM\u002FL\u002FXL) with justification\n6. **Risk assessment** — what can go wrong, data migration concerns, user impact\n7. **Acceptance criteria** — how you know the migration succeeded (expressed\n   against the chosen oracle\u002Fseam contracts, not against a not-yet-alive test\n   suite)\n\n#### Phase 5: Phased Implementation Plan\n\nProduce an ordered, phased plan. Each phase should be independently deployable\n(no half-migrated states that can't run in production).\n\n**Phase gating is regime-aware (applies to every phase).** State this rule at the\ntop of the phased plan and honor it in every phase's exit criteria. A phase is\n**not complete** until its Verification & Exit Criteria pass. Those criteria must\nbe (a) **objectively verifiable**; (b) **actually executed and recorded** before\nthe next phase starts; and (c) **gated** — do not advance to phase N+1 until\nphase N's criteria are demonstrably met. **But which criteria are valid depends\non the component's regime (Phase 2c):**\n\n- **Post-testability (\"lit\") phases:** exit criteria are runnable commands \u002F green\n  CI — **green CI on the phase's branch\u002FPR is the authoritative signal.**\n- **Pre-testability (\"dark\") phases:** the component isn't alive yet, so a green\n  CI test gate is a **category error**. Exit criteria come from the achievable\n  safety-ladder rung instead — captured seam\u002Foracle snapshots, reversibility\n  scaffolding proven present, a passed smoke checklist, recorded review. Do **not**\n  block a dark-regime phase on a test suite that can't run yet.\n\nReport to the user any phase whose pass\u002Ffail is unknown rather than assuming it\npassed.\n\n**The first phase establishes maximum *achievable* safety — not a fixed \"green\nlegacy gate.\"** Do not hard-code \"resurrect everything and make CI green.\" Shape\nthe first phase from the Phase 2 outputs, per component:\n\n- **Strategy A (Freeze-then-lift), component is resurrectable:** the first phase\n  *is* the classic Safety Net & Baseline — purely additive, no behavior change:\n  - **Characterization \u002F golden \u002F contract tests** at the **seams** that pin\n    current observable behavior (protocol traces, API snapshots, output goldens).\n  - **CI + lint + formatter** wired up and green (an authoritative gate for later\n    lit-regime phases).\n  - **Pinned dependencies \u002F committed lockfile** and a recorded known-good\n    baseline (versions, toolchain, how it builds and runs today).\n  - **\"Net proven to fail.\"** Deliberately mutate the code (e.g., change one\n    protocol code or return value), confirm the new tests go **red**, then\n    revert. A safety net that never fails is proof of nothing — prove it has\n    teeth.\n- **Strategy B (Beachhead\u002Fwalking-skeleton), component is dead:** the first phase\n  is **\"reach the Testability Milestone with the smallest slice\"** — drive the\n  thinnest end-to-end path onto the modern stack until it builds, boots, and runs\n  ≥1 real test green, capturing seam\u002Foracle contracts from the old system to\n  validate against. **Do not try to net the corpse.** Its exit criterion is the\n  achievable safety-ladder rung with residual risk named — a **blessed downgrade\n  is not a failure.**\n\nOnly after the first phase's criteria are met (at whatever rung) do the\nsubsequent infrastructure and feature phases begin.\n\nStructure each phase as:\n\n```markdown\n### Phase N: [Name] (T-shirt size: M)\n\n**Goal:** [One sentence]\n**Regime:** [pre-testability (\"dark\") | post-testability (\"lit\")] — per component\n**Safety rung:** [L0–L4, with residual risk named if below L4]\n**Prerequisites:** [Which phases must complete first]\n**Duration estimate:** [Relative, not calendar — e.g., \"2-4 sprints\"]\n\n#### Tasks\n| ID | Task | Component | Blocked by |\n|----|------|-----------|------------|\n| N.1 | ... | ... | — |\n| N.2 | ... | ... | N.1 |\n\n#### Risks & Mitigations\n- **Risk:** ... → **Mitigation:** ...\n\n#### Decisions made\n- [Every sub-decision this phase depends on, resolved and documented here so the\n  phase can be implemented without further user input. State \"dropped\" vs\n  \"deferred\" explicitly for anything cut.]\n\n#### Verification & Exit Criteria (Definition of Done)\n- [ ] [Regime-appropriate criterion. For LIT phases: a runnable command \u002F green\n      CI check, citing the actual command from the Commands & Verification\n      Inventory. For DARK phases: the achievable safety-ladder rung's evidence —\n      captured seam\u002Foracle snapshots, reversibility proven, smoke checklist\n      passed — NOT a green test suite the component can't yet run.]\n- [ ] [Include a parity\u002Fcharacterization check against the chosen oracle whenever\n      the change is meant to preserve behavior.]\n- [ ] [If purely additive, assert it: \"no behavior\u002Fdependency\u002Flogic changed.\"]\n- [ ] [If exiting below L4, state the residual risk and which later phase closes\n      it (e.g., \"client test gate deferred to the client-migration phase\").]\n```\n\n**Ordering principles:**\n- **Locate the Testability Milestone first**, per component — schedule the\n  smallest slice that reaches it early rather than deferring \"testable\" to the end\n  while demanding a gate at the start.\n- **Never require a component's automated test gate before it crosses its own\n  testability line.**\n- **Name the CI Milestone in the roadmap.** State explicitly which phase stands\n  up CI (the first *lit* phase, at\u002Fafter the Testability Milestone) so the reader\n  never has to guess when CI arrives — and flag that *enforcing* it (required\n  status check \u002F branch protection) is a manual human step, not an agent task.\n- **First-phase safety before behavior change** — establish the highest\n  achievable rung (not necessarily a full green gate) before modifying behavior.\n- Infrastructure and cross-cutting concerns next (auth, config, logging, CI\u002FCD)\n- Highest-risk or highest-value features next (prove the pattern early)\n- Low-risk, low-coupling features last (easy wins to parallelize)\n- Data migrations get their own phase with rollback plans\n\n#### Phase 6: Execution Governance\n\nModernization plans fail in execution, not on paper. Bake in the governance that\nkeeps each phase honest and reversible (generic across any ecosystem):\n\n- **Branch per phase.** Never commit phase work to the default branch. Open one\n  PR per phase; let CI on the PR be the authoritative green signal before merge\n  **for lit-regime phases**. For dark-regime phases, the PR still carries the\n  rung's evidence (captured contracts, smoke results, reversibility scaffolding).\n- **Merge to trunk before the next phase; never stack (H7).** Each phase branch\n  is cut **from trunk**, and its PR is **merged to trunk before the next phase\n  starts**. Never base a phase branch or its PR on a *sibling* phase branch — that\n  is how PRs get merged into each other, the trunk silently stalls several phases\n  behind, and later phases are forced into the exact bind where the no-stacking\n  rule has to be broken. Before starting a phase, verify the previous phase is\n  merged to trunk and `git log origin\u002F\u003Ctrunk>..HEAD` is empty at branch creation.\n  **If controlled stacking is genuinely unavoidable, it is allowed only with a\n  required reconciliation PR** that lands the stack onto trunk **and an explicit\n  residual-risk note** — never as a silent default.\n- **Confirm the trunk name; retire legacy defaults.** Pin the repo's real trunk\n  (e.g. `main`) and, if a second default-ish branch exists (`master`), mark it\n  \"history only — do not target\" so phase work never lands on the wrong branch.\n- **The gate matches the regime.** Lit phases advance on green CI; dark phases\n  advance on the achievable safety-ladder rung with residual risk named — not on\n  a \"looks done\" judgement, and not on a test suite that can't run yet.\n- **Stand up CI at the CI Milestone, and hand off enforcement to a human.**\n  Name the phase that introduces CI (the first lit phase). Distinguish the two\n  steps: authoring the workflow file is agent-doable; making it an **enforced\n  required status check \u002F branch-protection (or MR-approval) rule is a manual\n  platform-UI step the agent cannot perform.** Until a human configures it, CI\n  *runs* but does not *block* merges — so record \"enable branch protection \u002F\n  required checks\" as an explicit user action item (in the CI phase's exit\n  criteria and in §9 stakeholder decisions), never as a completed agent task.\n- **Interface-preserving & independently deployable.** Each phase leaves the\n  system runnable, so rollback = redeploy the previous version. Prefer\n  interface-preserving rewrites (wrap internals behind a stable interface) and\n  prove equivalence with the seam\u002Foracle contracts (golden\u002Fcharacterization\n  tests where they exist).\n- **Living plan.** Update `MODERNIZATION_PLAN.md` status markers as each phase's\n  exit criteria are met — ✅ complete \u002F ⏭️ descoped \u002F 🗑️ dropped — record the\n  decisions made during implementation, and **update the safety-ladder rung \u002F\n  residual-risk register** as components cross their testability lines.\n- **Keep the executable docs alive too (H8).** The living-plan discipline is not\n  only the plan file. Any phase that changes **topology** — module\u002Freactor\n  membership, removed services, renamed branches, changed commands, new\u002Fremoved\n  endpoints — must update `.github\u002Fcopilot-instructions.md`, the `README`, and any\n  module\u002Ftopology list **in the same PR**. Treat those doc updates as part of the\n  phase's Definition of Done, not a follow-up — a stale \"quarantined module\" list\n  or a hard-coded old-branch link actively misleads the next agent\u002Fhuman.\n- **Red-team each phase before implementing it (Phase 2.5).** Walk the phase plan\n  against `references\u002Fmigration-hazards.md` (H1–H8) and fold the fixes into tasks\n  and exit criteria before writing code. Record the cleared checklist in the\n  phase's \"Decisions made\".\n- **Emit editable instructions.** Produce a `.github\u002Fcopilot-instructions.md`\n  (create the `.github\u002F` directory if needed) from the template at\n  `references\u002Fcopilot-instructions.template.md` — a commands table plus the\n  regime-aware phase-gate and branch\u002FPR rules — so the executing agent\u002Fhuman has\n  the canonical commands and gates in the location GitHub Copilot auto-loads. The\n  user edits it to their own gates. If a `.github\u002Fcopilot-instructions.md` already\n  exists, do not overwrite it — merge the commands\u002Fgating\u002Fbranch sections in, or\n  write the generated file alongside as\n  `.github\u002Fcopilot-instructions.modernization.md` and tell the user to merge.\n\n#### Phase 7: Migration Safety Net\n\nDocument the operational guardrails needed:\n\n- **Feature flags** — what gets flagged and how old\u002Fnew coexist\n- **Data migration strategy** — schema changes, backfills, dual-write periods.\n  For a **stateful data-store major upgrade** with persisted volumes (H5), an\n  engine image\u002Ftag bump is **not** a migration: pick and document one path —\n  a sequential\u002Ffeature-compatibility-version upgrade with steps + rollback, **or**\n  an explicit **destructive reset** (drop volumes, re-seed) when the data is\n  ephemeral\u002Fdemo — stated as a deliberate decision, with the prior-major image\n  retained for rollback. (e.g. Mongo 3→7 over an existing `\u002Fdata\u002Fdb` volume needs\n  `down -v` + re-seed for a demo, or a staged FCV upgrade for real data.)\n- **Rollback plan** — per phase, how to revert if something fails\n- **Transitional-insecure-state register (H6)** — every deliberately-weak state\n  introduced to keep the system runnable mid-migration (permit-all shims, CSRF\n  disabled, an open endpoint, a placeholder secret) listed with: why it's needed,\n  the phase that **closes** it, the residual risk, and a by-design-until-phase-N\n  note for reviewers. Scope each weakening as tightly as possible (e.g. a\n  permit-all chain should still explicitly disable form-login\u002FHTTP-Basic).\n  Pre-declaring these converts recurring scanner\u002Freviewer churn into a tracked\n  decision.\n- **Oracle & seam contracts** — which running instance \u002F recorded I\u002FO \u002F golden\n  snapshots (or a **self-frozen golden master**, when no external reference is\n  available or permitted) serve as the behavioral reference, and how new work is\n  diffed against them\n- **Testing strategy** — what new test coverage is needed (built on the *target*\n  stack as components cross their testability line), and what stays quarantined\n- **Observability** — metrics\u002Falerts that prove the new system matches the old\n\n### Output Structure\n\nProduce a primary Markdown file named `MODERNIZATION_PLAN.md` with:\n\n1. Executive summary (one paragraph: what, why, rough scope)\n2. Current state assessment (from architecture doc)\n3. **Feasibility spike result & strategy** — per component: spike findings, the\n   A\u002FB migration strategy, the located **Testability Milestone**, the target\n   **safety-ladder rung**, and a **residual-risk register** for anything below L4;\n   plus the plan-wide **CI Milestone** (which phase stands up CI) with a note that\n   *enforcing* it is a manual human step\n4. Target architecture with ADRs\n5. Per-feature migration analysis (with testability status + safety rung)\n6. Phased implementation plan — first phase establishes the highest *achievable*\n   safety rung (not a fixed green legacy gate); every phase is labeled\n   pre\u002Fpost-testability and carries regime-appropriate, gated exit criteria; the\n   **CI Milestone phase is named explicitly** and lists \"enable branch protection\n   \u002F required status checks\" as a manual user action\n7. Execution governance (branch-per-phase, regime-aware gate, living-plan status)\n8. Migration safety net (oracle & seam contracts, flags, rollback, observability)\n9. Open questions \u002F decisions needed from stakeholders — including any manual\n   platform-configuration handoffs the agent cannot perform (e.g. enabling\n   required status checks \u002F branch protection to make CI an enforced gate)\n\nAlso emit a companion **`.github\u002Fcopilot-instructions.md`** (the path GitHub\nCopilot auto-loads; create `.github\u002F` if absent) from\n`references\u002Fcopilot-instructions.template.md`, populated with the project's\ncanonical commands and phase-gating \u002F branch rules, for whoever executes the\nplan to edit and adopt. Never overwrite an existing\n`.github\u002Fcopilot-instructions.md` — merge into it or write a sibling\n`.github\u002Fcopilot-instructions.modernization.md` and flag it for the user.\n\n### Conventions\n\n- **Cite the architecture doc** when referencing current state rather than\n  restating everything. Keep this document forward-looking.\n- **Be opinionated.** Make concrete recommendations, not \"you could do A or B.\"\n  State what you'd pick and why. The user can override.\n- **Scope realistically.** A modernization plan that tries to change everything at\n  once is fiction. Identify what's phase 1 vs. \"future consideration.\"\n- **Resolve every in-phase decision during planning.** A phase plan must carry\n  all the sub-decisions its implementation depends on, already decided and\n  documented (the \"Decisions made\" block), so the phase can be executed without\n  going back to the user. State **\"dropped\" vs \"deferred\"** explicitly for\n  anything cut — they are not the same. Reserve `[DECISION NEEDED]` for genuine\n  *stakeholder\u002Fbusiness* choices (budget, team size, product direction, timeline\n  pressure) that block a phase; drive those to resolution with the user during\n  planning rather than leaving them open in an implementable phase.\n- **Don't gold-plate.** If a component works fine on the old stack and has no\n  maintenance burden, \"leave it alone\" is a valid recommendation.\n- **Assume dead-by-default; make safety adaptive.** Don't demand a fully-green\n  legacy CI gate up front. Run the feasibility spike, pick the highest achievable\n  safety-ladder rung, and treat a **downgrade as a blessed outcome** with residual\n  risk named — never a failure.\n- **Locate testability in time.** Every plan must name its **Testability\n  Milestone** per component and never require a component's automated test gate\n  before that component crosses its own testability line.\n- **Name the CI Milestone, hand enforcement to a human.** State which phase\n  stands up CI (the first lit phase), and make explicit that turning CI into an\n  *enforced* required check \u002F branch-protection rule is a manual platform step\n  the agent cannot do — surface it as a user action item, not a done task.\n- **Net the seams, not the corpse.** Anchor safety at externally observable\n  contracts (protocols, schemas, wire\u002Ffile formats, endpoints) with a ranked\n  oracle (running instance → recorded I\u002FO → code-as-spec → **self-frozen golden\n  master** when no external reference exists or is permitted). Don't sink sprints\n  resurrecting a dead toolchain just to run a test that gets deleted at rewrite.\n- **Keep it generic.** Express commands and gates in terms of *the project's*\n  package manager \u002F test runner \u002F CI — never assume a specific stack.\n- **Red-team every phase before implementing (H1–H8).** Walk each phase plan\n  against `references\u002Fmigration-hazards.md` and fold the fixes into tasks\u002Fexit\n  criteria first — a hazard caught in planning is a task; in review, rework; in\n  prod, an incident. These tactical hazards (incomplete quarantine, framework\n  codemods, runtime\u002Fbase-image lockstep, route-class enumeration, data-store\n  upgrade paths, transitional-insecure-state noise, stacked-PR\u002Ftrunk drift,\n  living-doc drift) are what strategic scaffolding alone keeps missing.\n",{"name":5,"description":7},"main","58843b159d7a4050d6b785a98b908cce505c0b92",".agents\u002Fskills\u002Fdoc-and-modernize",0,"https:\u002F\u002Fgithub.com\u002FReihantt6\u002Fsns-myagent","https:\u002F\u002Fgithub.com\u002FReihantt6","reihsns.web.id","2026-08-19 20:08:18",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add Reihantt6\u002Fsns-myagent --skill doc-and-modernize",{"tool":38,"command":39},"bunx","bunx skills add Reihantt6\u002Fsns-myagent --skill doc-and-modernize",{"tool":41,"command":42},"pnpm","pnpm dlx skills add Reihantt6\u002Fsns-myagent --skill doc-and-modernize","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FReihantt6\u002Fsns-myagent\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fdoc-and-modernize\u002FSKILL.md",true,[46,52],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"references\u002Fcopilot-instructions.template.md","REFERENCE","参考文档",7857,"https:\u002F\u002Fgithub.com\u002FReihantt6\u002Fsns-myagent\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fdoc-and-modernize\u002Freferences\u002Fcopilot-instructions.template.md",{"path":53,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":54,"sourceHtmlUrl":55},"references\u002Fmigration-hazards.md",14189,"https:\u002F\u002Fgithub.com\u002FReihantt6\u002Fsns-myagent\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fdoc-and-modernize\u002Freferences\u002Fmigration-hazards.md",[57,64,71,78,85,92],{"skillNo":58,"name":59,"nameZh":6,"description":60,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":61,"categories":62,"keywords":63,"publishedAt":19},"01M77XDCYZ407XYMF2T4P6F7VT","youtube-transcript","Extract transcripts from YouTube videos. Use when the user asks for a transcript, subtitles, or captions of a YouTube video and provides a YouTube URL (youtube.com\u002Fwatch?v=, youtu.be\u002F, or similar). Supports output with or without timestamps.","https:\u002F\u002Fgithub.com\u002FReihantt6\u002Fsns-myagent\u002Fblob\u002Fmain\u002Fagent\u002Fskills\u002Fyoutube-transcript\u002FSKILL.md",[],[],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":70,"publishedAt":19},"01M77XD7PBC98J6MXGJJ2TJ8DX","youtube-thumbnail-design","YouTube thumbnail design with specific dimensions, contrast rules, and mobile preview optimization. Covers safe zones, text placement, face expression psychology, and A\u002FB testing. Use for: YouTube thumbnails, video cover images, click-through optimization. Triggers: youtube thumbnail, thumbnail design, video thumbnail, click through rate, ctr optimization, youtube cover, video cover image, thumbnail maker, thumbnail tips, youtube design, video preview image","https:\u002F\u002Fgithub.com\u002FReihantt6\u002Fsns-myagent\u002Fblob\u002Fmain\u002Fagent\u002Fskills\u002Fyoutube-thumbnail-design\u002FSKILL.md",[],[],{"skillNo":72,"name":73,"nameZh":6,"description":74,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M77XD2541C8HXJ6RHYZP4NGJ","youtube-short-maker","Make YouTube Shorts that hold attention with Pexo — vertical 9:16, fast-paced, hook in the first 3 seconds. Describe your topic and Pexo writes the script, generates the shots, picks the models, and assembles a finished Short with music and captions. Use for YouTube Shorts: \"youtube short\", \"make a youtube short\", \"shorts video\", \"short-form video\". NOT for long-form or landscape video.","https:\u002F\u002Fgithub.com\u002FReihantt6\u002Fsns-myagent\u002Fblob\u002Fmain\u002Fagent\u002Fskills\u002Fyoutube-short-maker\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":82,"categories":83,"keywords":84,"publishedAt":19},"01M77XCXKVSYK7KTZ3PQBVVGFD","xcode-project-setup","Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Firebase, Alamofire).","https:\u002F\u002Fgithub.com\u002FReihantt6\u002Fsns-myagent\u002Fblob\u002Fmain\u002Fagent\u002Fskills\u002Fxcode-project-setup\u002FSKILL.md",[],[],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M77XCR1DV8ZQK2NHWKVY4EWX","x402","Set up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key. Two setups it works out up front — \"just use it\" (set up a wallet so you or Claude Code can run cloud browser tasks paid from the wallet — Claude writes and runs throwaway scripts, nothing touches your codebase) or \"build it in\" (install the SDK and write the key + code into your project). Walks through wallet setup, funding, .env, and a ~$1 test run. Use when the user asks about x402, pay-per-use, USDC payments, or wants Browser Use Cloud without an API key. For the free-tier signup (reverse-CAPTCHA → API key), use `browser-use cloud signup` or the `cloud` skill instead.","https:\u002F\u002Fgithub.com\u002FReihantt6\u002Fsns-myagent\u002Fblob\u002Fmain\u002Fagent\u002Fskills\u002Fx402\u002FSKILL.md",[],[],{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":19},"01M77XCMD3R3ZBZQQSW6E0793B","x-twitter-scraper","Build GitHub Copilot workflows with Xquik X API SDKs, REST endpoints, hosted Apify Actor runs, MCP tools, TweetClaw OpenClaw plugin installs, signed webhooks, tweet search, user lookup, follower exports, media actions, and agent automation.","https:\u002F\u002Fgithub.com\u002FReihantt6\u002Fsns-myagent\u002Fblob\u002Fmain\u002Fagent\u002Fskills\u002Fx-twitter-scraper\u002FSKILL.md",[],[]]