@caddis/cli 0.4.22 → 0.4.24

package/bundles/antigravity-plugin/skills/port-to-github/scripts/Test-PortContentPolicy.ps1

@@ -0,0 +1,218 @@
+<#
+.SYNOPSIS
+  Check a staged repository against the source-only content policy, over the tips AND all history.
+
+.DESCRIPTION
+  The policy: a repository holds application code, configuration and templates, migration
+  SCRIPTS, tests, and the scripts/manifests that rebuild the environment. It does NOT hold:
+
+    runtime      a runtime or server distribution (MariaDB, PHP, JDK, Node, Python, Apache...)
+    binary       compiled or packaged files (.exe .dll .so .jar .msi, archives)
+    db-data      database data files (ibdata1, *.ibd, *.frm, *.mdf, SQLite files, dumps)
+    data-export  data files above the size threshold (.csv .xlsx .json .xml .sql ...), or any
+                 data file under a backups/dumps/exports folder
+    dependency   installed dependencies (node_modules, vendor, .venv, site-packages)
+    backup       editor and copy backups (*.bak, *.orig, *.old, *~)
+
+  Large files that match no rule are reported as 'large-review' (a decision, not a violation).
+
+  .gitignore does not remove a file that was committed before it: every excluded path is
+  checked in ALL history, not only in the current files.
+
+  Reads <staging>\<Name>\mirror.git. Changes nothing. Writes content-policy.json next to it.
+  Exit 0: compliant. Exit 1: at least one excluded path exists somewhere in history.
+
+  Project overrides (optional) in the config file, key "contentPolicy":
+    { "keep": ["regex", ...], "exclude": ["regex", ...], "dataThresholdMB": 5, "largeMB": 10 }
+  Regexes match the repository path (forward slashes).
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory)][string]$Name,
+    [string]$StagingRoot,
+    [string]$ConfigPath,
+    [double]$DataThresholdMB,
+    [double]$LargeMB,
+    # Print every finding, not only the per-folder summary.
+    [switch]$Detail
+)
+
+$ErrorActionPreference = 'Stop'
+. (Join-Path $PSScriptRoot 'PortCommon.ps1')
+
+$config = Get-PortConfig $ConfigPath
+$stage = Join-Path (Get-PortStagingRoot $config $StagingRoot) $Name
+$mirror = Join-Path $stage 'mirror.git'
+if (-not (Test-Path -LiteralPath $mirror)) { throw "No staged mirror at $mirror. Run Get-PortSource.ps1 first." }
+$manifest = Get-Content -LiteralPath (Join-Path $stage 'manifest.json') -Raw | ConvertFrom-Json
+$branch = $manifest.defaultBranch
+
+$policy = Get-PortConfigValue $config 'contentPolicy' $null
+$keepRx = @(); $extraExcludeRx = @()
+if ($policy) {
+    if ($policy.PSObject.Properties.Name -contains 'keep') { $keepRx = @($policy.keep) }
+    if ($policy.PSObject.Properties.Name -contains 'exclude') { $extraExcludeRx = @($policy.exclude) }
+    if (-not $DataThresholdMB -and $policy.PSObject.Properties.Name -contains 'dataThresholdMB') { $DataThresholdMB = [double]$policy.dataThresholdMB }
+    if (-not $LargeMB -and $policy.PSObject.Properties.Name -contains 'largeMB') { $LargeMB = [double]$policy.largeMB }
+}
+if (-not $DataThresholdMB) { $DataThresholdMB = 5 }
+if (-not $LargeMB) { $LargeMB = 10 }
+$dataBytes = [int64]($DataThresholdMB * 1MB)
+$largeBytes = [int64]($LargeMB * 1MB)
+
+# A runtime folder is the runtime's NAME, optionally followed by a version or platform tag
+# (php-8.3.33, jdk-17.0.2, node-v20.11.0-win-x64, apache24). Not any folder that merely STARTS
+# with one: redis-migrations/ or apache-poi-wrapper/ are source.
+$ver = '([-_ ]?v?\d[\w.]*(-(win|linux|x64|x86|amd64|arm64)[\w.-]*)?)?'
+$runtimeDirRx = "(?i)^(mariadb|mysql|mysql-server|php|jdk|jre|openjdk|java|python|python-embed|nodejs|node|apache|httpd|nginx|tomcat|apache-tomcat|redis|postgres|postgresql|pgsql|erlang|ruby|dotnet|go)$ver$"
+$runtimeBinRx = '(?i)^(mariadbd|mysqld|mariadb|mysql|php|php-cgi|node|python|pythonw|java|javaw|httpd|nginx|redis-server|postgres|pg_ctl|erl|ruby|dotnet)\.exe$'
+$dependencyDirRx = '(?i)^(node_modules|vendor|\.venv|venv|site-packages|bower_components|\.yarn|jspm_packages)$'
+$binaryExtRx = '(?i)\.(exe|dll|so|dylib|msi|msix|bin|iso|img|jar|war|ear|class|pyc|pdb|lib|a|o|obj|zip|7z|tar|gz|tgz|rar|bz2|xz|cab|nupkg|whl|deb|rpm)$'
+$dbDataRx = '(?i)(^|/)(ibdata\d*|ib_logfile\d*|ib_buffer_pool|aria_log[\w.]*|undo\d+)$|\.(ibd|frm|myd|myi|mdf|ldf|ndf|sqlite3?|db3|dmp)$'
+$backupRx = '(?i)(\.(bak|orig|old|swp)|~)$'
+$dataExtRx = '(?i)\.(csv|tsv|xlsx|xlsm|xlsb|xls|ods|parquet|avro|orc|jsonl|ndjson|json|xml|sql|dat|txt|log)$'
+$dataDirRx = '(?i)^(backups?|dumps?|exports?|snapshots?|data-?dumps?)$'
+
+function Get-Category([string]$Path, [int64]$Bytes) {
+    foreach ($rx in $keepRx) { if ($Path -match $rx) { return $null } }
+    foreach ($rx in $extraExcludeRx) { if ($Path -match $rx) { return 'project-exclude' } }
+    $parts = $Path -split '/'
+    $dirs = if ($parts.Count -gt 1) { $parts[0..($parts.Count - 2)] } else { @() }
+    $leaf = $parts[-1]
+    foreach ($d in $dirs) { if ($d -match $runtimeDirRx) { return 'runtime' } }
+    if ($leaf -match $runtimeBinRx) { return 'runtime' }
+    foreach ($d in $dirs) { if ($d -match $dependencyDirRx) { return 'dependency' } }
+    if ($Path -match $dbDataRx) { return 'db-data' }
+    if ($leaf -match $backupRx) { return 'backup' }
+    if ($leaf -match $binaryExtRx) { return 'binary' }
+    if ($leaf -match $dataExtRx) {
+        # Under a backups/dumps folder any data file is excluded, but a plain note (.txt/.md) is not data.
+        if ($leaf -notmatch '(?i)\.(txt|md)$') { foreach ($d in $dirs) { if ($d -match $dataDirRx) { return 'data-export' } } }
+        # Migration SCRIPTS stay by policy. A large .sql under migration(s)/ may be a script or a
+        # data load, so it is a decision, not an automatic exclusion. Data FILES there (csv, json,
+        # xlsx) are still data.
+        if ($leaf -match '(?i)\.sql$' -and ($dirs | Where-Object { $_ -match '(?i)^migrations?$' })) {
+            if ($Bytes -ge $largeBytes -or $Bytes -ge $dataBytes) { return 'large-review' }
+            return $null
+        }
+        if ($Bytes -ge $dataBytes) { return 'data-export' }
+    }
+    if ($Bytes -ge $largeBytes) { return 'large-review' }
+    return $null
+}
+
+function MGit([string[]]$a) { Invoke-PortGit (@('-C', $mirror) + $a) }
+
+# ---- every blob in history, with every path it ever had ----------------------------------
+Write-PortStep 'Reading every path and blob in history'
+$pathsBySha = @{}
+$submodules = New-Object System.Collections.Generic.HashSet[string]
+function Add-PathForSha([string]$sha, [string]$p) {
+    if (-not $pathsBySha.ContainsKey($sha)) { $pathsBySha[$sha] = New-Object System.Collections.Generic.HashSet[string] }
+    [void]$pathsBySha[$sha].Add($p)
+}
+# EVERY path a blob was ever written to. rev-list --objects names each blob only ONCE, by the
+# first path it meets, so identical content at a second path was invisible (found by the
+# dogfood: a 3-byte test image at two paths survived a clean). log --raw lists every add or
+# change, per commit, including merges (-m) and root commits.
+foreach ($l in (MGit @('-c', 'core.quotePath=false', 'log', '--all', '--raw', '--no-abbrev', '--no-renames', '-m', '--root', '--format=', '--diff-filter=AMT'))) {
+    if (-not $l -or $l[0] -ne ':') { continue }
+    $meta, $p = $l -split "`t", 2
+    $f = $meta -split ' '
+    if ($f.Count -lt 4 -or -not $p -or $f[3] -match '^0+$') { continue }
+    # Mode 160000 is a submodule: its "blob" is a commit in ANOTHER repository, invisible to a
+    # size scan. Record it, so a runtime vendored as a submodule cannot pass unnoticed.
+    if ($f[1] -eq '160000') { [void]$submodules.Add($p); continue }
+    Add-PathForSha $f[3] $p
+}
+# Safety net: anything reachable that the log did not show.
+foreach ($l in (MGit @('rev-list', '--objects', '--all'))) {
+    $sha, $p = $l -split ' ', 2
+    if ($p -and -not $pathsBySha.ContainsKey($sha)) { Add-PathForSha $sha $p }
+}
+$sizeBySha = @{}
+foreach ($l in (MGit @('cat-file', '--batch-all-objects', '--batch-check=%(objecttype) %(objectname) %(objectsize)'))) {
+    $t, $o, $s = $l -split ' '
+    if ($t -eq 'blob' -and $pathsBySha.ContainsKey($o)) { $sizeBySha[$o] = [int64]$s }
+}
+
+# Aggregate per path: largest version, number of versions.
+$byPath = @{}
+foreach ($sha in $sizeBySha.Keys) {
+    foreach ($p in $pathsBySha[$sha]) {
+        if (-not $byPath.ContainsKey($p)) { $byPath[$p] = [pscustomobject]@{ path = $p; maxBytes = [int64]0; versions = 0 } }
+        $e = $byPath[$p]; $e.versions++
+        if ($sizeBySha[$sha] -gt $e.maxBytes) { $e.maxBytes = $sizeBySha[$sha] }
+    }
+}
+
+$tipFiles = @{}
+foreach ($l in (MGit @('-c', 'core.quotePath=false', 'ls-tree', '-r', '--name-only', $branch))) { $tipFiles[$l] = $true }
+
+# ---- classify ----------------------------------------------------------------------------------
+$findings = New-Object System.Collections.Generic.List[object]
+foreach ($e in $byPath.Values) {
+    $cat = Get-Category $e.path $e.maxBytes
+    if (-not $cat) { continue }
+    $findings.Add([pscustomobject]@{
+            path = $e.path; category = $cat; maxBytes = $e.maxBytes; versions = $e.versions
+            inDefaultBranch = [bool]$tipFiles[$e.path]
+            action = if ($cat -eq 'large-review') { 'review' } else { 'exclude' }
+        })
+}
+foreach ($sm in $submodules) {
+    $findings.Add([pscustomobject]@{ path = $sm; category = 'submodule'; maxBytes = [int64]0; versions = 1; inDefaultBranch = [bool]$tipFiles[$sm]; action = 'review' })
+}
+$exclude = @($findings | Where-Object { $_.action -eq 'exclude' })
+$review = @($findings | Where-Object { $_.action -eq 'review' })
+
+# Group by top two path segments so a 3,000-file vendored runtime reads as one line.
+# Group by folder, at most 4 levels deep, so one vendored runtime reads as one line and a
+# data folder deep in an app is still named precisely.
+function Get-Group([string]$p) { $s = $p -split '/'; if ($s.Count -le 1) { return $p }; $d = $s[0..([math]::Min(3, $s.Count - 2))]; ($d -join '/') + '/' }
+$groups = @($findings | Group-Object { "$($_.category)|$(Get-Group $_.path)" } | ForEach-Object {
+        $cat, $grp = $_.Name -split '\|', 2
+        [pscustomobject]@{
+            category = $cat; group = $grp; files = $_.Count
+            historyMB = [math]::Round((($_.Group | Measure-Object maxBytes -Sum).Sum) / 1MB, 1)
+            inDefaultBranch = @($_.Group | Where-Object { $_.inDefaultBranch }).Count
+        }
+    } | Sort-Object historyMB -Descending)
+
+$totalBytes = [int64]0; foreach ($v in $sizeBySha.Values) { $totalBytes += $v }
+# Count each blob once, even when it sits at several excluded paths (a per-path sum can exceed
+# the whole history). Plain loops: Measure-Object on NO input has no .Sum under strict mode.
+$exPaths = New-Object System.Collections.Generic.HashSet[string]
+foreach ($x in $exclude) { [void]$exPaths.Add($x.path) }
+$exBytes = [int64]0
+foreach ($sha in $sizeBySha.Keys) { foreach ($p in $pathsBySha[$sha]) { if ($exPaths.Contains($p)) { $exBytes += $sizeBySha[$sha]; break } } }
+$report = [ordered]@{
+    name = $Name; defaultBranch = $branch; checkedAt = (Get-Date).ToString('o')
+    thresholds = [ordered]@{ dataThresholdMB = $DataThresholdMB; largeMB = $LargeMB }
+    historyBlobMB = [math]::Round($totalBytes / 1MB, 1)
+    excludedPaths = $exclude.Count; excludedMB = [math]::Round($exBytes / 1MB, 1)
+    reviewPaths = $review.Count
+    compliant = ($exclude.Count -eq 0)
+    groups = $groups
+    findings = @($findings | Sort-Object maxBytes -Descending)
+}
+ConvertTo-PortJsonFile $report (Join-Path $stage 'content-policy.json')
+# Plain path list, one per line, for Invoke-PortHistoryClean.ps1 and for .gitignore review.
+Set-Content -LiteralPath (Join-Path $stage 'content-policy-exclude.txt') -Value @($exclude | Sort-Object path | ForEach-Object { $_.path }) -Encoding UTF8
+
+Write-Host ''
+Write-Host ("Content policy for {0}: {1} excluded path(s), {2} MB of history; {3} path(s) to review. History holds {4} MB of blobs in total." -f $Name, $exclude.Count, $report.excludedMB, $review.Count, $report.historyBlobMB)
+if ($groups.Count -gt 0) {
+    Write-Host ''
+    Write-Host ('{0,-13} {1,-55} {2,7} {3,10} {4}' -f 'category', 'where', 'files', 'MB', 'in default branch')
+    foreach ($g in $groups) { Write-Host ('{0,-13} {1,-55} {2,7} {3,10} {4}' -f $g.category, $g.group, $g.files, $g.historyMB, $g.inDefaultBranch) }
+}
+if ($Detail) { $findings | Sort-Object maxBytes -Descending | ForEach-Object { Write-Host ('  {0,-13} {1,9:N0} KB  {2}' -f $_.category, ($_.maxBytes / 1KB), $_.path) } }
+Write-Host "    report: $(Join-Path $stage 'content-policy.json')"
+Write-Host "    exclude list: $(Join-Path $stage 'content-policy-exclude.txt')"
+if ($exclude.Count -gt 0) {
+    Write-PortWarn 'Not compliant. Decide per group: keep (add a "keep" regex to contentPolicy), or remove from history with Invoke-PortHistoryClean.ps1. Adding a path to .gitignore does NOT remove it from history.'
+    exit 1
+}
+Write-PortOk 'Compliant: no excluded content anywhere in history.'
+exit 0

package/bundles/antigravity-plugin-extras/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis-extras",
-  "version": "1.3.33",
+  "version": "1.3.34",
   "description": "caddis-extras — the long-tail skills for the Antigravity (agy) caddis plugin; install alongside caddis for the full set."
 }

package/bundles/antigravity-plugin-extras/skills/_registry.md

@@ -48,6 +48,7 @@
 
 | Skill | Path | When to Use |
 |-------|------|-------------|
+| Adopt App | `adopt-app/` | Bring an app that was never scaffolded - a proof of concept that became real, a folder on a server, a checkout with no remote - up to the standard a generated app starts at. Inventories it without running it (local folder, network share, or a remote Windows box over WinRM), works out what stack each component is, measures it against an adoption standard with three verdicts (pass, gap, and question-only-a-person-can-answer), and writes an ordered plan whose steps cannot be done in the wrong order. Use when the user says "this app was never set up properly", "adopt this POC", "onboard this app", "it just runs from a folder on the server", "bring this up to standard", "what would it take to get this into CI", "nobody knows how this is deployed", or "it started as a prototype and now it is production". |
 | Changelog Generator | `changelog-generator/` | Automatically creates user-facing changelogs from git commits by analyzing commit history, categorizing changes, and transforming technical commits into clear, customer-friendly release notes. Turns hours of manual changelog writing into minutes of automated generation. |
 | Deploy Local | `deploy-local/` | End-to-end local deployment loop for Gitea-hosted projects. Use when the user wants to commit on dev, push to remote, monitor the golden CI/build/deploy workflow, validate prod on the configured prod host, and fix lint/test/pipeline failures until deployment is healthy. |
 | Monorepo | `monorepo/` | Monorepo management with Turborepo and pnpm workspaces. Use for Turborepo setup, turbo.json task dependencies, remote caching, pnpm workspace protocol, shared packages (ui-library, config, types), affected-only CI/CD builds, or monorepo structure (apps/ vs packages/). Covers pitfalls like circular deps, version drift, and hoisting issues. |

package/bundles/antigravity-plugin-extras/skills/adopt-app/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: adopt-app
+description: Bring an app that was never scaffolded - a proof of concept that became real, a folder on a server, a checkout with no remote - up to the standard a generated app starts at. Inventories it without running it (local folder, network share, or a remote Windows box over WinRM), works out what stack each component is, measures it against an adoption standard with three verdicts (pass, gap, and question-only-a-person-can-answer), and writes an ordered plan whose steps cannot be done in the wrong order. Use when the user says "this app was never set up properly", "adopt this POC", "onboard this app", "it just runs from a folder on the server", "bring this up to standard", "what would it take to get this into CI", "nobody knows how this is deployed", or "it started as a prototype and now it is production".
+---
+
+# adopt-app
+
+An app that was never scaffolded is missing things a generated app gets for free: a repository
+on the team's host, CI, a declared stack, a health signal, a rollback. This skill finds out
+exactly which of them are missing, what only a person can answer, and in what order to fix it.
+
+**It never runs the app.** It reads files, file metadata, git state and what the host has
+registered to start the folder. It does not execute an entry point, an installer, a build or a
+migration. The app is usually the only copy of something already in production.
+
+**It changes nothing outside its own output folder.** Every phase is read-only. The last phase
+writes a plan; a different, team-specific skill performs it.
+
+| Phase | Script | Writes |
+|---|---|---|
+| 1. Inventory | `Get-AppInventory.ps1` | `inventory.json` |
+| 2. Stack | `Resolve-AppProfile.ps1` | `profile.json` |
+| 3. Conformance | `Test-AppConformance.ps1` | `conformance.json`, `answers.json` |
+| 4. Plan | `New-AdoptionPlan.ps1` | `adoption-plan.md`, `adoption.json` |
+
+Output goes to `<outDir>/<name>/`, by default `.caddis/adopt/<name>/` under the current repo.
+Scripts are PowerShell 7 (`pwsh`); the code that runs on a remote box is Windows PowerShell 5.1
+compatible.
+
+## Before you start
+
+1. **Read the project config** if one exists: `.caddis/adopt-app.json`, or `$env:ADOPT_APP_CONFIG`.
+   Six keys, every one of them read by a named script: `outDir`, `fileBudget`, `skipFolders`,
+   `skipPattern`, `untrackedThresholdMB`, and `expectedRemotePattern` - the regex that says what
+   "the team's host" means here. Without that pattern the skill cannot tell a team repository from
+   a personal one, and it says so rather than assuming. Shape and per-key detail:
+   `references/config.example.json`.
+2. **Find out where the app really is.** A folder on a developer's machine may be a stale copy of
+   a server folder, or the only copy in existence. Phase 1 reports which, but ask as well.
+3. **Say up front that nothing will be run or changed.** People are right to be nervous about a
+   tool pointed at a production folder.
+
+## Phase 1 - inventory
+
+```powershell
+$s = '<path-to-this-skill>/scripts'
+& $s/Get-AppInventory.ps1 -Path <folder> [-Name <short-name>] [-ComputerName <box>]
+```
+
+| Where the app is | How to point at it |
+|---|---|
+| this machine | `-Path E:\legacy-app` |
+| a network share | `-Path \\fileserver\apps\legacy-app` |
+| a remote Windows box | `-Path G:\apps\legacy-app -ComputerName appserver01` |
+
+Prefer `-ComputerName` for anything on a server. A share scan works but is slow, and the host
+facts - services, scheduled tasks, web sites - can only be read on the box itself.
+
+**Read four things in the output before going on.**
+
+- **Is the scan complete?** A budget or an access denial makes it PARTIAL: sizes become MINIMUMS,
+  the script exits 1, and `-AllowPartial` is how you accept that on the record. Never treat a
+  partial scan's "nothing found" as "nothing there". Raise `-FileBudget`, or use
+  `-SkipFolder <name>` to spend the budget where the answer is still open. A skipped folder is
+  recorded as NOT SCANNED, never as empty, and it prevents later checks from passing.
+- **Neither committed nor ignored.** Folders in this state are the real hazard: one `git add -A`
+  puts them in the history for ever. A filename pattern cannot find them - only git can.
+- **Possible credentials.** The heuristics are tuned to be readable rather than exhaustive: they
+  skip comments, type declarations, template references and expressions. **Read every file they
+  flag yourself.** A credential that was ever committed must be ROTATED, not only deleted.
+- **What runs it.** If nothing on the host references the folder and the app is live, it runs
+  somewhere you have not looked. Find out where before planning anything.
+
+Junctions and symlinks are reported and never followed. A junction inside a tree that git manages
+is a data-loss hazard: git's recursive remove follows it and deletes the target's contents.
+
+## Phase 2 - what kind of app is it
+
+```powershell
+& $s/Resolve-AppProfile.ps1 -Name <short-name> [-ForceProfile <profile>]
+```
+
+A profile describes one KIND of component - how to detect it, its runtimes, build, services or
+schedule, routing, config, data, CI and deploy. `profiles/` holds the starting set; the contract
+is in `references/profile-contract.md`.
+
+An app is a SET of components. The script reports **every** profile that matches each component
+folder, not just the winner, because a folder can honestly be two things and picking one silently
+hides a decision. Anything in `alsoMatches` is a question for the owner - leftover scaffolding
+from an abandoned rewrite matches its own stack perfectly and is not part of the app.
+
+- **No profile matched** (exit 2) means the rules do not describe this stack yet, not that the app
+  has none. Copy `profiles/_template` into a new folder and fill it in. Set `status` to `draft`;
+  only a stack that something has actually automated end to end may be `proven`.
+- **A draft profile** is a description, not an automation. Follow it by hand and write down what
+  you did, so it can earn `proven` later.
+
+## Phase 3 - conformance
+
+```powershell
+& $s/Test-AppConformance.ps1 -Name <short-name>
+```
+
+Three verdicts, and the third is the point:
+
+| | means |
+|---|---|
+| `PASS` | observed true |
+| `GAP` | observed false, with the evidence named |
+| `ASK` | **not observable from files.** A person must answer it. |
+
+Who owns an app, which of 127 branches is the truth, how it is deployed today, whether the
+rollback has ever been run - none of these are in the files. A tool that forces them into
+pass-or-fail produces a confident wrong answer that nobody rechecks.
+
+**An unanswered ASK on a blocking item stops the adoption exactly as a GAP does** (exit 2, versus
+exit 1 for a gap). Record answers as they arrive; they persist in `answers.json`:
+
+```powershell
+& $s/Test-AppConformance.ps1 -Name app -Answer owner="Team Payments" -Answer canonical-branch=main
+```
+
+`-Waive <id>` records an accepted exception. It is stored as a waiver and never rewritten as a
+pass - six months later the difference is the whole value of the record.
+
+The standard, item by item and why each one is there: `references/standard.md`.
+
+## Phase 4 - the plan
+
+```powershell
+& $s/New-AdoptionPlan.ps1 -Name <short-name> [-HandoverSkill <team-skill>]
+```
+
+The order is the product. Doing these in the wrong order costs real work:
+
+- Create the repository before settling what may be in it, and removing it later means rewriting
+  history other people have already cloned.
+- Rotate a credential after publishing, and it was public in between.
+- Wire up CI before anyone says which branch is the truth, and CI builds the wrong branch.
+
+Each step carries why it is there, what to do, and the check that says it is done. Steps that
+cannot start yet are listed as blocked, with the reason - a plan that omits what it cannot do
+reads like a shorter job.
+
+Give `adoption-plan.md` to the owner. Agree it before anything is changed.
+
+## Handover
+
+This skill says WHAT must be true. It does not know your hosts, ports, routing or CI, so it does
+not perform the adoption. Pass the plan to the team-specific skill that does, and name that skill
+with `-HandoverSkill` so the plan does not end in mid-air.
+
+For the repository move itself, use the **port-to-github** skill: it stages the source read-only,
+keeps every branch and tag, verifies by SHA, and never pushes back to the source.
+
+Re-run phase 3 after each step. It is the same gate either way, so the work cannot quietly drift
+from the standard.
+
+## Rules that apply to every phase
+
+- **Never run the app.** Not the installer, not the build, not a migration, not "just the health
+  check". Reading is always enough to plan.
+- **A partial answer must not read as a clean one.** Every script says when it did not finish, and
+  reports a minimum rather than a wrong total.
+- **File contents never go into an artefact.** A config file holds credentials and a report gets
+  copied into tickets and chats. Paths, line numbers and key NAMES only.
+- **A check that cannot fail is worse than no check**, and so is one that cannot pass. Both
+  manufacture confidence. Every script here exits non-zero on the failure it exists for; do not
+  pipe one to `Out-Null` or read only its last line.
+- **Stage files by name.** The apps this skill is pointed at routinely hold gigabytes that are
+  neither committed nor ignored, so `git add -A` in one of them is how they become permanent.
+- Code that runs on a remote box runs under Windows PowerShell 5.1. There, with
+  `$ErrorActionPreference='Stop'`, a native command's stderr is a terminating error even with
+  `2>$null`. Use `'Continue'` and judge native commands by `$LASTEXITCODE`.

package/bundles/antigravity-plugin-extras/skills/adopt-app/profiles/_template/profile.json

@@ -0,0 +1,55 @@
+{
+  "name": "<stack-name>",
+  "status": "placeholder",
+  "description": "<one sentence: what kind of component this is>",
+  "detect": {
+    "allFiles": ["<file every such repo has>"],
+    "anyFiles": ["<file any of which indicates it>"],
+    "noneFiles": ["<file that rules it out>"],
+    "fileContains": [{ "file": "<file or glob>", "pattern": "<regex>" }],
+    "noneContain": [{ "file": "<file or glob>", "pattern": "<regex that rules it out>" }]
+  },
+  "runtimes": [
+    {
+      "kind": "<runtime>",
+      "version": "<exact, or where it is declared>",
+      "provision": "<how it gets onto a box, e.g. installed manually, or a provisioning script>"
+    }
+  ],
+  "build": [{ "what": "<step>", "command": "<command>", "cwd": "<folder, optional>" }],
+  "services": [
+    {
+      "role": "<api|web|worker|database>",
+      "port": "<the app's HTTP port>",
+      "start": "<start command>",
+      "manager": "<how the process is kept running, e.g. a service manager or a container runtime>",
+      "bind": "<the interface it binds - loopback-only unless a trusted edge forwards identity>",
+      "health": "<health check>"
+    }
+  ],
+  "schedule": {
+    "trigger": "<only for batch components: a scheduler, a file-arrival watcher, or a manual/CI trigger>"
+  },
+  "routing": {
+    "mode": "<reverse-proxy|rewrite-rule|dedicated-site|none>",
+    "staticRoot": "<built static files, optional>",
+    "apiPrefix": "</api>"
+  },
+  "config": {
+    "files": ["<per-environment config files>"],
+    "rule": "<how config is kept out of version control>"
+  },
+  "data": {
+    "migrations": "<tool or none>",
+    "state": "<where state lives and how it is restored>"
+  },
+  "ci": {
+    "workflow": "<CI workflow file>",
+    "requiredJobs": ["<job>"],
+    "deployJob": "<job>"
+  },
+  "deploy": {
+    "script": "<deploy script>",
+    "verify": ["<a check that would FAIL on a broken deploy>"]
+  }
+}

package/bundles/antigravity-plugin-extras/skills/adopt-app/profiles/batch-job/profile.json

@@ -0,0 +1,68 @@
+{
+  "name": "batch-job",
+  "status": "draft",
+  "description": "A scheduled or triggered batch engine with no web API: a CLI run by a scheduler, with inputs, outputs, a schedule and an audit trail rather than a port or a route.",
+  "detect": {
+    "anyFiles": ["pyproject.toml", "requirements.txt"],
+    "fileContains": [
+      {
+        "file": ["pyproject.toml", "requirements.txt"],
+        "pattern": "(?i)\\[project\\.scripts\\]|\\btyper\\b|\\bclick\\b|\\bargparse\\b"
+      }
+    ],
+    "noneContain": [
+      {
+        "file": ["pyproject.toml", "requirements.txt"],
+        "pattern": "(?i)\\b(fastapi|django|flask|starlette|aiohttp)\\b"
+      }
+    ]
+  },
+  "runtimes": [
+    {
+      "kind": "python",
+      "version": "<from pyproject.toml's requires-python>",
+      "provision": "<installed on the host that runs it; a per-app virtual environment>"
+    },
+    {
+      "kind": "<other, e.g. a native library or a licensed asset the job depends on>",
+      "version": "<exact>",
+      "provision": "<provisioned separately; licensed assets come from their licensed source, never from version control>"
+    }
+  ],
+  "build": [
+    {
+      "what": "Dependencies",
+      "command": "pip install -e .  (or pip install -r requirements.txt)"
+    }
+  ],
+  "services": [],
+  "schedule": {
+    "trigger": "<a task scheduler, a file-arrival watcher, or a manual/CI trigger>",
+    "account": "<a service account, never a person's own login>",
+    "command": "<the CLI entry point, e.g. python -m <package> run>",
+    "overlap": "<what happens if a run is still going when the next one is due>"
+  },
+  "routing": {
+    "mode": "none"
+  },
+  "config": {
+    "files": ["<the config file the CLI reads>"],
+    "rule": "kept out of version control; a committed example file"
+  },
+  "data": {
+    "migrations": "none",
+    "state": "<input, staging and output locations, kept outside the repo; a retention rule; never committed, especially real customer data>"
+  },
+  "ci": {
+    "workflow": "<CI workflow file: lint, tests, a dry run against sanitised sample data>",
+    "requiredJobs": ["<lint_and_test>"],
+    "deployJob": "<deploy_prod (updates code and dependencies; does not itself run a batch)>"
+  },
+  "deploy": {
+    "script": "<deploy script: stop the schedule, update, re-enable; never mid-run>",
+    "verify": [
+      "a dry run against sanitised sample data exits zero and writes the expected output artefact",
+      "the next scheduled run completes and writes its expected output artefact"
+    ]
+  }
+}

package/bundles/antigravity-plugin-extras/skills/adopt-app/profiles/dotnet-service/profile.json

@@ -0,0 +1,67 @@
+{
+  "name": "dotnet-service",
+  "status": "draft",
+  "description": "An ASP.NET Core web API or web app (.NET 6+), optionally serving a built frontend from the same process.",
+  "detect": {
+    "anyFiles": ["**/*.csproj", "**/*.sln"],
+    "fileContains": [
+      {
+        "file": "**/*.csproj",
+        "pattern": "(?i)Microsoft\\.NET\\.Sdk\\.Web|Microsoft\\.AspNetCore"
+      }
+    ]
+  },
+  "runtimes": [
+    {
+      "kind": "dotnet",
+      "version": "<the target framework moniker in the .csproj, e.g. net8.0>",
+      "provision": "<the matching .NET runtime/SDK installed on dev and prod hosts>"
+    }
+  ],
+  "build": [
+    {
+      "what": "Restore and publish",
+      "command": "dotnet publish -c Release -o <publish folder>"
+    },
+    {
+      "what": "Frontend bundle, if the app serves one",
+      "command": "npm ci && npm run build",
+      "cwd": "<the frontend folder, if any>"
+    }
+  ],
+  "services": [
+    {
+      "role": "api",
+      "port": "<the app's HTTP port>",
+      "start": "dotnet <published .dll>",
+      "manager": "<a service manager or a container runtime>",
+      "bind": "<loopback-only, unless a trusted edge forwards identity>",
+      "health": "<a real health endpoint, e.g. /health via a health-checks middleware>"
+    }
+  ],
+  "routing": {
+    "mode": "reverse-proxy",
+    "staticRoot": "<built frontend output folder, if any, or wwwroot>",
+    "apiPrefix": "/api"
+  },
+  "config": {
+    "files": ["<a per-environment settings file, kept out of version control for real environments>"],
+    "rule": "real settings files are gitignored; a committed example settings file shows the shape only"
+  },
+  "data": {
+    "migrations": "<the app's migration tool, e.g. an ORM's migrations feature, or none>",
+    "state": "<an external database; nothing durable lives on the app host itself>"
+  },
+  "ci": {
+    "workflow": "<CI workflow file: restore, build, test, publish>",
+    "requiredJobs": ["<lint_and_test>"],
+    "deployJob": "<deploy_prod>"
+  },
+  "deploy": {
+    "script": "<deploy script: publish, stop, swap, start>",
+    "verify": [
+      "the health endpoint returns a body with a status field, not just HTTP 200",
+      "a rendered page or the frontend bundle's hash changed, so an old bundle behind a new backend cannot pass"
+    ]
+  }
+}