si-overnight 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,170 @@
1
- # Temporary Holding Version
1
+ # si-overnight
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Sen uyumadan gerekli kararları toplayan; sen yokken kod yazan, test eden ve
4
+ sabaha rapor bırakan taşınabilir agent skill'i.
5
+
6
+ ## Nasıl çalışır?
7
+
8
+ 1. Projeyi, mevcut değişiklikleri ve test düzenini inceler.
9
+ 2. Her yeni gece iki moddan hangisini istediğini sorar:
10
+ - **Liste:** Ana işleri, ardından önceden belirlediğin yedek işleri bitirir ve durur.
11
+ - **Keşif:** Ana işleri bitirince, belirlediğin alanlarda yararlı iyileştirmeler bulur ve uygular.
12
+ 3. Öncelikleri, başarı ölçütlerini, dokunulmayacak yerleri, bitiş saatini ve gereken
13
+ yetkileri sen uyumadan netleştirir. Cevapladığın şeyleri tekrar tekrar sormaz.
14
+ 4. Seçilen kapsamda uygular, test eder, hataları düzeltir ve sonuçları kaydeder.
15
+ Bir iş bloke olursa bağımsız işlere devam eder.
16
+ 5. `.si-overnight/<run-id>/run.md` dosyasına ilerlemeyi,
17
+ `report.md` dosyasına tamamlanan işleri, test sonuçlarını ve eksikleri yazar.
18
+
19
+ İş bitince, süre/kota dolunca veya ilerleyebileceği iş kalmayınca durur. Sırf token
20
+ harcamak için aynı testleri döndürmez veya proje dışında işler uydurmaz.
21
+
22
+ ## Kurulum
23
+
24
+ ### npm / npx
25
+
26
+ Node.js 20 veya üzeri yeterli; npm CLI'si Python gerektirmez ve ek paket bağımlılığı
27
+ yoktur. Henüz registry'ye yayımlanmadı. Bu depodan doğrudan çalıştır:
28
+
29
+ ```bash
30
+ node bin/si-overnight.mjs --platform all --project /projenin/tam/yolu
31
+ node bin/si-overnight.mjs --platform codex --scope user --dry-run
32
+ node bin/si-overnight.mjs --help
33
+ ```
34
+
35
+ Yerel npm paketi oluşturup registry kullanmadan çalıştırabilirsin:
36
+
37
+ ```bash
38
+ npm pack --ignore-scripts
39
+ npm exec --yes --package ./si-overnight-0.1.0.tgz -- si-overnight --platform all --project /projenin/tam/yolu
40
+ ```
41
+
42
+ Paket `si-overnight` adıyla yayımlandıktan sonra aynı kurulum:
43
+
44
+ ```bash
45
+ npx si-overnight --platform all --project /projenin/tam/yolu
46
+ npx si-overnight --platform codex --scope user
47
+ ```
48
+
49
+ `--platform` tekrarlanabilir: `--platform claude --platform pi`.
50
+ `--scope project` varsayılandır; `--project` mevcut bir dizin olmalıdır.
51
+ `--dry-run` yalnız hedefleri gösterir. Kurulum hedefin içindeki sembolik bağlantıları
52
+ izlemez; mevcut farklı dosyaları korur. Seçtiğin proje kökünün kendisi bir dizin
53
+ kısayoluysa gerçek kök kullanılır. Kurulum sırasında başka süreçler skill dizinlerini
54
+ değiştirmemelidir. `npm install` kendiliğinden skill kurmaz veya agent başlatmaz.
55
+
56
+ ### Python alternatifi
57
+
58
+ Python 3 ile, bu deponun kök dizininden çalıştır:
59
+
60
+ ```bash
61
+ # Tüm desteklenen platformlar için seçtiğin projeye kur.
62
+ python3 scripts/install.py --platform all --project /projenin/tam/yolu
63
+
64
+ # Ya da yalnız Codex için kullanıcı genelinde kur.
65
+ python3 scripts/install.py --platform codex --scope user
66
+
67
+ # Yazmadan önce hedefleri gör.
68
+ python3 scripts/install.py --platform all --scope user --dry-run
69
+ ```
70
+
71
+ Tek platform için `codex`, `claude`, `antigravity` veya `pi` seçebilirsin.
72
+ Kurulum mevcut farklı bir skill'in üzerine yazmaz; aynı sürüm zaten kuruluysa
73
+ değiştirmez. Güncellemede mevcut dizini inceleyip taşıdıktan sonra yeniden kur.
74
+ Kurulum izin ayarlarını değiştirmez ve arka plan süreci başlatmaz.
75
+ Seçtiğin proje veya kullanıcı kökü bir dizin bağlantısı olabilir; bu kökün altındaki
76
+ kurulum dizinlerinde sembolik bağlantı varsa kurulum reddedilir.
77
+
78
+ ## Çağırma
79
+
80
+ | Platform | Komut |
81
+ | --- | --- |
82
+ | Codex | `$si-overnight` veya `/skills` içinden seç |
83
+ | Claude Code | `/si-overnight` |
84
+ | Google Antigravity | `/si-overnight` |
85
+ | pi | `/skill:si-overnight` |
86
+
87
+ Örnek gece başlangıcı:
88
+
89
+ ```text
90
+ $si-overnight
91
+ Bu gece ödeme ekranındaki hata listesini bitir.
92
+ Sonra ne yapacağını ve ihtiyaç duyduğun kararları uyumadan bana sor.
93
+ 18 Kasım 2026 07:00 Europe/Istanbul'a kadar çalış.
94
+ ```
95
+
96
+ Devam etmek için aynı skill'i çağırıp ilgili
97
+ `.si-overnight/<run-id>/run.md` dosyasını belirt. Süre dolmuşsa yeni bir çalışma
98
+ aralığı ver. Önce dosyalarla checkpoint'i karşılaştırır, sonra kaldığı yerden ilerler.
99
+
100
+ Diğer Agent Skills uyumlu araçlarda `skills/si-overnight/` klasörünü aracın
101
+ belgelediği skill dizinine kopyalayabilirsin. Native skill desteği olmayan ama
102
+ dosya okuyabilen bir agente `SKILL.md` dosyasını okuyup uygulamasını söyleyebilirsin.
103
+ Her platformda aynı slash komutunun kayıtlı olduğu varsayılmaz.
104
+
105
+ ## Çalışma süresi sınırı
106
+
107
+ Skill tek başına uygulamayı açık tutmaz, bilgisayarın uyumasını engellemez,
108
+ sonlanan agenti yeniden başlatmaz veya kota yenilemez. Yerel çalışmada makine,
109
+ oturum ve gerekli servisler açık kalmalı; uzakta çalışmada gerçekten uzakta
110
+ çalışan bir ortam kullanılmalı. Oturum aniden kesilirse en son checkpoint'ten
111
+ devam edilir; kesilen süreç yeni bir sabah raporu yazamaz.
112
+
113
+ Codex'in Goal modu bulunan sürümlerinde, kararlaştırılan gece planını `/goal`
114
+ ile açıkça başlatabilirsin. Bu skill'i çağırmak kendiliğinden Goal modu oluşturmaz.
115
+ Başka hostlarda otomatik yeniden çağırma için ayrıca yapılandırılmış bir runner
116
+ gerekir; bu paket runner içermez. Kapsam ve onay mekanizmaları her durumda geçerlidir.
117
+
118
+ Platform yolları ve resmi kaynaklar:
119
+ [uyumluluk notları](skills/si-overnight/references/platforms.md).
120
+
121
+ ## Kontroller
122
+
123
+ ```bash
124
+ npm test
125
+ python3 -m unittest discover -s tests -v
126
+ ```
127
+
128
+ ## CI ve npm yayını
129
+
130
+ GitHub Actions her branch push'unda ve pull request'te Node.js 20 ve 24 ile iki
131
+ test takımını çalıştırır. Node.js 24 işi ayrıca `npm pack --ignore-scripts` ile
132
+ paketi oluşturur; boş bir npm cache'iyle, çevrimdışı ve geçici bir dizine kurar.
133
+ Kurulan komutu ve tüm skill kaynaklarının byte eşitliğini kontrol eder.
134
+ Test edilen `.tgz` ve SHA-256 özeti, 14 gün saklanan `npm-package` artifact'idir.
135
+ Bağımlılık ve lockfile olmadığı için `npm ci` gerekmez.
136
+
137
+ `v0.1.0` gibi bir `vMAJOR.MINOR.PATCH` etiketi push edilince `release.yml` aynı
138
+ kontrolleri yeniden çalıştırır. Etiket `package.json` sürümüyle aynı olmalıdır;
139
+ ön sürüm etiketleri reddedilir. Tüm işler başarılı olunca ayrı yayın işi artifact'in
140
+ özetini doğrular ve aynı tarball'ı npm'e public/provenance ile yayımlar.
141
+ Yalnız yayın işi OIDC izni alır; fork PR'ları yayın yapmaz. Action sürümleri
142
+ [GitHub'ın önerdiği tam commit SHA'larına](https://docs.github.com/en/actions/reference/security/secure-use#using-third-party-actions)
143
+ sabitlenmiştir. Paketleme, kurulum ve yayın lifecycle script'lerini çalıştırmaz.
144
+
145
+ Bir defalık npm kurulumu:
146
+
147
+ 1. npm hesabında `si-overnight` paketine yayın yetkisi edin. Paket henüz yoksa
148
+ önce etkileşimli npm oturumu/2FA ile bir başlangıç yayını yap veya npm'in
149
+ [staged publishing](https://docs.npmjs.com/staged-publishing/) akışıyla paket
150
+ kaydını oluştur. Trusted Publisher ayarı mevcut bir paket gerektirir;
151
+ [npm trust önkoşulları](https://docs.npmjs.com/cli/v11/commands/npm-trust/)
152
+ bunu belirtir. Başlangıçta yayımlanan sürüm tekrar yayımlanamaz; otomatik akışta
153
+ yeni bir sürüm kullan. Bu depodaki komutlar paket adının müsaitliğini veya
154
+ hesap yetkisini doğrulamaz.
155
+ 2. GitHub deposunun public, `package.json` içindeki `repository.url` değerinin
156
+ `git+https://github.com/siguelabs/si.git` olduğundan emin ol;
157
+ [npm provenance](https://docs.npmjs.com/generating-provenance-statements/)
158
+ kaynak deposuyla eşleşme gerektirir.
159
+ 3. npm → `si-overnight` → Settings → Trusted publishing altında **GitHub Actions**
160
+ ekle: organization/user **siguelabs**, repository **si**, workflow filename
161
+ **release.yml**; environment alanını boş bırak. **Allow npm publish** seçeneğini
162
+ etkinleştir. Yeni ayarın ilk başarılı yayınını iki gün içinde tamamla; süresi
163
+ geçerse ayarı yeniden oluştur. Ayrıntılar:
164
+ [npm Trusted Publishers](https://docs.npmjs.com/trusted-publishers/).
165
+ 4. Workflow dosyaları ve sürüm değişikliği depoya girdikten sonra eşleşen etiketi
166
+ push et. Yayın runner'ı Node.js 24 kullanır ve npm ≥11.5.1 koşulunu denetler;
167
+ OIDC'nin alt sınırları Node.js 22.14 ve npm 11.5.1'dir. Bu akışta `NPM_TOKEN`
168
+ veya başka bir registry secret'ı gerekmez. Tag push'undan sonra yayın otomatik
169
+ başlar; GitHub'da `v*` etiketlerini kimin oluşturabildiğini repository ruleset
170
+ ile sınırla.
@@ -0,0 +1,48 @@
1
+ #!/usr/bin/env node
2
+
3
+ import { parseArgs } from 'node:util';
4
+ import { installSkill } from '../lib/install.mjs';
5
+
6
+ const help = `Usage: si-overnight --platform <name> [options]
7
+
8
+ Install the si-overnight skill. No agent process or background job is started.
9
+
10
+ Options:
11
+ --platform <name> codex, claude, antigravity, pi, or all (repeatable)
12
+ --scope <scope> project (default) or user
13
+ --project <path> Existing target project directory (default: current directory)
14
+ --dry-run Show destinations without writing files
15
+ --help, -h Show this help
16
+
17
+ Examples:
18
+ si-overnight --platform all --project /path/to/project
19
+ si-overnight --platform codex --scope user
20
+ si-overnight --platform claude --platform pi --dry-run
21
+ `;
22
+
23
+ try {
24
+ const { values } = parseArgs({
25
+ options: {
26
+ platform: { type: 'string', multiple: true },
27
+ scope: { type: 'string', default: 'project' },
28
+ project: { type: 'string' },
29
+ 'dry-run': { type: 'boolean', default: false },
30
+ help: { type: 'boolean', short: 'h' },
31
+ },
32
+ strict: true,
33
+ allowPositionals: false,
34
+ });
35
+ if (values.help) {
36
+ process.stdout.write(help);
37
+ } else {
38
+ installSkill({
39
+ platforms: values.platform,
40
+ scope: values.scope,
41
+ project: values.project,
42
+ dryRun: values['dry-run'],
43
+ });
44
+ }
45
+ } catch (error) {
46
+ console.error(`Install failed: ${error.message}`);
47
+ process.exitCode = 1;
48
+ }
@@ -0,0 +1,151 @@
1
+ import {
2
+ lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync,
3
+ } from 'node:fs';
4
+ import { homedir } from 'node:os';
5
+ import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
6
+ import { fileURLToPath } from 'node:url';
7
+
8
+ export const SKILL_SOURCE = fileURLToPath(new URL('../skills/si-overnight/', import.meta.url));
9
+ const PROJECT_PATHS = {
10
+ codex: '.agents/skills',
11
+ claude: '.claude/skills',
12
+ antigravity: '.agents/skills',
13
+ pi: '.pi/skills',
14
+ };
15
+ const USER_PATHS = {
16
+ codex: '.agents/skills',
17
+ claude: '.claude/skills',
18
+ antigravity: '.gemini/config/skills',
19
+ pi: '.pi/agent/skills',
20
+ };
21
+
22
+ function inspect(path) {
23
+ try {
24
+ return lstatSync(path);
25
+ } catch (error) {
26
+ if (error.code === 'ENOENT') return undefined;
27
+ throw error;
28
+ }
29
+ }
30
+
31
+ function within(root, path) {
32
+ const suffix = relative(root, path);
33
+ return suffix === '' || (!isAbsolute(suffix) && suffix !== '..' && !suffix.startsWith(`..${sep}`));
34
+ }
35
+
36
+ function snapshot(directory) {
37
+ const result = new Map();
38
+ const visit = (path, name) => {
39
+ const stat = inspect(path);
40
+ if (!stat || stat.isSymbolicLink()) throw new Error(`Missing path or symbolic link: ${path}`);
41
+ if (stat.isDirectory()) {
42
+ result.set(name, null);
43
+ for (const child of readdirSync(path).sort()) visit(join(path, child), join(name, child));
44
+ } else if (stat.isFile()) {
45
+ result.set(name, readFileSync(path));
46
+ } else {
47
+ throw new Error(`Expected a regular file or directory: ${path}`);
48
+ }
49
+ };
50
+ visit(directory, '');
51
+ return result;
52
+ }
53
+
54
+ function equalSnapshots(first, second) {
55
+ if (first.size !== second.size) return false;
56
+ for (const [name, content] of first) {
57
+ if (!second.has(name)) return false;
58
+ const other = second.get(name);
59
+ if (content === null ? other !== null : other === null || !content.equals(other)) return false;
60
+ }
61
+ return true;
62
+ }
63
+
64
+ function checkParents(root, destination) {
65
+ if (!within(root, destination) || destination === root) throw new Error('Destination must be inside the selected root.');
66
+ let path = root;
67
+ const pieces = relative(root, destination).split(sep);
68
+ for (const piece of pieces) {
69
+ path = join(path, piece);
70
+ const stat = inspect(path);
71
+ if (!stat) continue;
72
+ if (stat.isSymbolicLink() || !stat.isDirectory()) {
73
+ throw new Error(`Refusing a symbolic link or non-directory in destination path: ${path}`);
74
+ }
75
+ }
76
+ }
77
+
78
+ function ensureParents(root, destination) {
79
+ let path = root;
80
+ for (const piece of relative(root, dirname(destination)).split(sep)) {
81
+ path = join(path, piece);
82
+ try {
83
+ mkdirSync(path);
84
+ } catch (error) {
85
+ if (error.code !== 'EEXIST') throw error;
86
+ }
87
+ const stat = lstatSync(path);
88
+ if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error(`Unsafe destination parent: ${path}`);
89
+ }
90
+ }
91
+
92
+ export function installationTargets({ platforms, scope = 'project', project = process.cwd(), userHome = homedir() }) {
93
+ if (!Array.isArray(platforms) || platforms.length === 0) throw new Error('--platform is required.');
94
+ for (const platform of platforms) {
95
+ if (platform !== 'all' && !Object.hasOwn(PROJECT_PATHS, platform)) throw new Error(`Unknown platform: ${platform}`);
96
+ }
97
+ if (scope !== 'project' && scope !== 'user') throw new Error('--scope must be project or user.');
98
+ const paths = scope === 'project' ? PROJECT_PATHS : USER_PATHS;
99
+ const root = realpathSync(resolve(scope === 'project' ? project : userHome));
100
+ if (!lstatSync(root).isDirectory()) throw new Error(`Selected root is not a directory: ${root}`);
101
+ const names = platforms.includes('all') ? Object.keys(paths) : platforms;
102
+ return { root, destinations: [...new Set(names.map((name) => join(root, paths[name], 'si-overnight')))] };
103
+ }
104
+
105
+ export function installSkill({
106
+ platforms, scope = 'project', project = process.cwd(), userHome = homedir(),
107
+ dryRun = false, source = SKILL_SOURCE, log = console.log,
108
+ } = {}) {
109
+ const { root, destinations } = installationTargets({ platforms, scope, project, userHome });
110
+ const sourcePath = resolve(source);
111
+ const expected = snapshot(sourcePath);
112
+ if (!Buffer.isBuffer(expected.get('SKILL.md'))) throw new Error(`Missing source SKILL.md: ${sourcePath}`);
113
+ const canonicalSource = realpathSync(sourcePath);
114
+ const pending = new Set();
115
+
116
+ // Check every destination before creating anything, including shared host paths.
117
+ for (const destination of destinations) {
118
+ if (within(canonicalSource, destination) || within(destination, canonicalSource)) {
119
+ throw new Error(`Source and destination overlap: ${destination}`);
120
+ }
121
+ checkParents(root, destination);
122
+ if (inspect(destination)) {
123
+ if (!equalSnapshots(expected, snapshot(destination))) {
124
+ throw new Error(`Existing destination differs; nothing overwritten: ${destination}`);
125
+ }
126
+ } else {
127
+ pending.add(destination);
128
+ }
129
+ }
130
+
131
+ for (const destination of destinations) {
132
+ if (!pending.has(destination)) {
133
+ log(`Already installed: ${destination}`);
134
+ } else if (dryRun) {
135
+ log(`Would install: ${destination}`);
136
+ } else {
137
+ checkParents(root, destination);
138
+ ensureParents(root, destination);
139
+ // Exclusive mkdir/write prevents merging into or overwriting a destination.
140
+ mkdirSync(destination);
141
+ for (const [name, content] of expected) {
142
+ if (name === '') continue;
143
+ const path = join(destination, name);
144
+ if (content === null) mkdirSync(path);
145
+ else writeFileSync(path, content, { flag: 'wx', mode: 0o644 });
146
+ }
147
+ log(`Installed: ${destination}`);
148
+ }
149
+ }
150
+ return destinations;
151
+ }
package/package.json CHANGED
@@ -1,6 +1,34 @@
1
1
  {
2
2
  "name": "si-overnight",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Install a portable overnight coding workflow for Codex, Claude Code, Antigravity, and pi.",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/siguelabs/si.git"
8
+ },
9
+ "type": "module",
10
+ "bin": {
11
+ "si-overnight": "bin/si-overnight.mjs"
12
+ },
13
+ "files": [
14
+ "bin/",
15
+ "lib/",
16
+ "skills/si-overnight/",
17
+ "README.md"
18
+ ],
19
+ "engines": {
20
+ "node": ">=20"
21
+ },
22
+ "scripts": {
23
+ "test": "node --test tests/*.test.mjs"
24
+ },
25
+ "keywords": [
26
+ "agent-skills",
27
+ "codex",
28
+ "claude-code",
29
+ "antigravity",
30
+ "pi",
31
+ "overnight"
32
+ ],
33
+ "license": "UNLICENSED"
34
+ }
@@ -0,0 +1,179 @@
1
+ ---
2
+ name: si-overnight
3
+ description: Prepare and execute unattended overnight coding work. Interview the user before they leave, choose a fixed queue or scoped improvement discovery, implement and test, checkpoint progress, and leave a morning report. Use when the user asks to keep working while they sleep or invokes si-overnight.
4
+ ---
5
+
6
+ # SI Overnight
7
+
8
+ Turn the user's available agent time into finished, verified project work while
9
+ they are away. Use the user's language for questions, checkpoints, and reports.
10
+
11
+ This skill supplies a workflow, not a background process. It cannot keep a
12
+ computer awake, restart an agent, create new turns after the host stops, bypass
13
+ approvals, or extend a provider quota. Explain relevant limitations once before
14
+ the user leaves. Use the host's existing execution facilities; do not silently
15
+ install a supervisor, schedule jobs, or weaken permission settings. For setup or
16
+ invocation differences, read [references/platforms.md](references/platforms.md).
17
+
18
+ ## 1. Inspect before interviewing
19
+
20
+ Read applicable project instructions and inspect the current workspace, existing
21
+ changes, task context, build scripts, test setup, and available tools. Identify
22
+ likely blockers without reading secret values. Do not start implementation yet.
23
+ Check whether a previous overnight run is being resumed before creating a new one.
24
+
25
+ Ask only consequential questions that inspection and the current conversation do
26
+ not answer. Batch them so the user can answer before sleeping. Use the host's
27
+ question tool when available, otherwise a concise numbered message.
28
+
29
+ For **every new overnight run**, explicitly ask which mode to use, unless the
30
+ user has already chosen for this run:
31
+
32
+ - **Queue:** Finish the agreed primary tasks, then the agreed backup tasks, then
33
+ stop. Do not invent additional implementation work.
34
+ - **Discover:** Finish the primary tasks, then find and implement useful
35
+ improvements within agreed project areas, categories, and exclusions.
36
+
37
+ Neither mode is a permanent preference. Do not silently inherit last night's
38
+ mode. On a resume, retain this run's mode and ask only about material changes.
39
+
40
+ Resolve the following in the same interview, reusing explicit answers:
41
+
42
+ - Primary outcomes, priority, and observable acceptance criteria. Offer concrete
43
+ candidates from the project if the user has not supplied tasks.
44
+ - Backup tasks for Queue; allowed areas and kinds of improvement for Discover.
45
+ Ask whether dependency changes or broad refactors are included when relevant.
46
+ - Paths, behavior, APIs, data, or design decisions that must remain unchanged.
47
+ - A stop time with date and timezone, or a duration; any known spend/token cap.
48
+ Offer a bounded duration if the user has no preference. Do not invent a cap.
49
+ - The expected checks and available test environment. Identify missing credentials,
50
+ services, network access, dependencies, and anticipated permission prompts now.
51
+ - Delivery expectations and permissions that matter for these tasks: local edits,
52
+ commits, push/PR, deployments, migrations, or external services. Propose local
53
+ edits and a report for unspecified delivery. Reuse existing authorization.
54
+
55
+ In Discover mode, propose a concrete discovery boundary, such as bug fixes,
56
+ regression tests, and small accessibility improvements in named directories.
57
+ "Use all my tokens" expresses willingness to work; it does not define a project
58
+ scope. Do not accept unbounded unrelated work as a substitute for scope.
59
+
60
+ If questions are pending, continue useful read-only preparation. Do not treat
61
+ silence, elapsed time, or the user going offline as an answer. If a question only
62
+ affects an optional branch, defer that branch and proceed with independently
63
+ authorized work. A bare invocation with no actionable scope must stay in intake.
64
+
65
+ ## 2. Save the run contract and start
66
+
67
+ Use [references/run-template.md](references/run-template.md) to create a compact
68
+ `.si-overnight/<unique-run-id>/run.md` in the target project. Use a timestamp plus
69
+ a collision suffix if needed. Preserve existing runs. Record the workspace,
70
+ baseline changes, chosen mode, exact scope, user answers, authorization, deadline,
71
+ acceptance criteria, task order, test plan, and next action. Never save credentials.
72
+
73
+ Show a short resolved plan and begin as soon as the necessary answers are in.
74
+ The user's answers are the go-ahead for the agreed work; do not add a ceremonial
75
+ "may I start?" round. If the user explicitly says wait, wait.
76
+
77
+ Before they leave, run proportionate baseline checks and a representative command
78
+ that exercises the expected permissions. Surface concrete setup blockers while
79
+ they can still answer. Do not promise that preflight prevents all future prompts.
80
+ Preserve existing user edits; use an isolated branch/worktree when appropriate
81
+ and supported, checking that its environment works. Never reset or stash user
82
+ changes merely to obtain a clean tree.
83
+
84
+ Keep the run files local and exclude them from staging unless the user asks to
85
+ version them. Do not change repository ignore/configuration files just to hide
86
+ these artifacts. If checkpoints cannot be written, disclose the limitation and
87
+ use an available approved persistent location; do not claim durable recovery.
88
+
89
+ ## 3. Execute without requiring a conversation
90
+
91
+ Repeat while useful authorized work and budget remain:
92
+
93
+ 1. Read the checkpoint and check the current time, scope, and available budget.
94
+ Reserve enough remaining time for verification and a handoff. If the host
95
+ exposes reliable usage telemetry, use it; otherwise report quota as unknown.
96
+ 2. Select the highest-priority unblocked task. Keep tasks small enough to verify
97
+ independently. Resolve ordinary implementation choices using the contract
98
+ and project conventions instead of asking the absent user.
99
+ 3. Implement the change and add meaningful regression coverage where warranted.
100
+ Use bounded, noninteractive commands; avoid watch modes, interactive prompts,
101
+ and commands that wait indefinitely. Stop only processes started by this run.
102
+ 4. Run focused checks, fix demonstrated regressions, and run the broader checks
103
+ required by the project or the acceptance criteria. Distinguish baseline
104
+ failures from new failures and unavailable checks from passing checks.
105
+ 5. Review the resulting diff for correctness, scope, and unrelated changes.
106
+ Record the evidence and next action before moving to the next task.
107
+
108
+ Use available subagents for independent work when it helps; assign nonoverlapping
109
+ write ownership and verify their outputs. Do not assume every host supports them.
110
+ The same scope, deadline, and permissions apply to every worker.
111
+
112
+ Do not end with "I can continue if you want" while authorized work remains.
113
+ Continue within the active execution until completion, a stop condition, or a
114
+ host limit. A progress message is not a handoff requiring the user to reply.
115
+
116
+ In **Queue** mode, consume only the approved primary and backup queues.
117
+ In **Discover** mode, inspect for evidence-backed candidates after the primary
118
+ queue, rank by user impact and confidence, and implement one bounded improvement
119
+ at a time. Record each candidate's evidence, fit with the agreed scope, and
120
+ acceptance check before editing. Prefer reproducible bugs, missing regression
121
+ coverage, and improvements with observable benefit over speculative rewrites.
122
+ If no worthwhile candidate remains, stop and report that fact.
123
+
124
+ Run tests to obtain evidence, not to spend tokens. Do not disable tests, loosen
125
+ assertions, hide diagnostics, or change product requirements to manufacture a
126
+ pass. Do not repeatedly rerun unchanged passing checks without a new reason.
127
+
128
+ ## 4. Handle surprises and stop conditions
129
+
130
+ When a task needs a new consequential decision, unavailable access, or an action
131
+ outside the contract, record the precise blocker and continue independent
132
+ authorized work. If a runtime approval is required, follow the host's approval
133
+ mechanism; prior agreement does not override it. Do not block the entire queue
134
+ on an optional deployment or credential-dependent integration.
135
+
136
+ Permission to discover improvements does not add permission to publish, deploy,
137
+ send messages, spend money, access new sensitive data, or alter unrelated projects.
138
+ Perform such actions only with applicable explicit authorization and host approval.
139
+ Never weaken sandboxing, permissions, tests, or security controls to keep running.
140
+
141
+ After three failed attempts on the same blocker without meaningful new evidence,
142
+ checkpoint it and move to another task. Retry transient failures only with bounded
143
+ backoff inside the remaining budget; do not wait indefinitely for quota resets.
144
+
145
+ Stop when any of these holds:
146
+
147
+ - The chosen queue is complete, or scoped discovery has no worthwhile work left.
148
+ - The agreed deadline or an observable budget/provider limit is reached.
149
+ - All remaining work depends on unavailable access, approval, or a user decision.
150
+ - The user asks to stop, or the host ends execution.
151
+
152
+ Checkpoint after every completed task, material failed attempt, permission blocker,
153
+ and before a risky operation or context handoff. Include work in progress and its
154
+ verification state. On foreseeable shutdown or quota exhaustion, save the report
155
+ if possible. A sudden termination may leave only the last checkpoint; never
156
+ promise an after-the-fact report from a stopped process.
157
+
158
+ ## 5. Resume and leave the morning report
159
+
160
+ On resume, read the contract, checkpoint, current instructions, workspace diff,
161
+ and recent changes before acting. Reconcile the files with the recorded state;
162
+ do not assume an interrupted command succeeded. Check for other actors' edits.
163
+ Do not redo completed work or silently expand scope. If the deadline has expired,
164
+ write a handoff and obtain a new execution window before more implementation.
165
+ If a new approval is needed, preserve progress and identify the affected task.
166
+
167
+ Write `.si-overnight/<run-id>/report.md` in the user's language and give a short
168
+ chat handoff linking it. Report:
169
+
170
+ - Completed outcomes and their acceptance evidence.
171
+ - Changed files and any commits/PRs actually created under the agreed permissions.
172
+ - Exact check commands, observed outcomes, and checks that could not run.
173
+ - Incomplete work, blockers, assumptions, and any unverified changes.
174
+ - Why execution stopped, remaining useful work, and one concrete resume prompt
175
+ naming this run's `run.md`.
176
+
177
+ Mark completion only when the relevant acceptance criteria are satisfied. Leave
178
+ blocked or unverified work clearly identified. Never claim all available tokens
179
+ were consumed without reliable measurement.
@@ -0,0 +1,56 @@
1
+ # Host compatibility
2
+
3
+ The same `SKILL.md` implements the workflow. Installation and invocation differ
4
+ by host. These paths and commands were checked against official documentation on
5
+ 2026-11-17; installed versions and organization settings can differ.
6
+
7
+ | Host | Project skill directory | User skill directory | Invocation |
8
+ | --- | --- | --- | --- |
9
+ | Codex | `.agents/skills/si-overnight/` | `~/.agents/skills/si-overnight/` | `$si-overnight` or select via `/skills` |
10
+ | Claude Code | `.claude/skills/si-overnight/` | `~/.claude/skills/si-overnight/` | `/si-overnight` |
11
+ | Google Antigravity | `.agents/skills/si-overnight/` | `~/.gemini/config/skills/si-overnight/` | `/si-overnight` |
12
+ | pi | `.pi/skills/si-overnight/` | `~/.pi/agent/skills/si-overnight/` | `/skill:si-overnight` |
13
+
14
+ Each directory contains `SKILL.md` and its supporting files. Pi also supports
15
+ `.agents/skills` and `~/.agents/skills`. Antigravity retains legacy `.agent/skills`
16
+ compatibility; use the current path for new installations.
17
+
18
+ Do not promise a literal `/si-overnight` command on every platform. On other
19
+ Agent Skills-compatible hosts, use that host's documented discovery path and
20
+ invocation mechanism. If skills are unsupported but file reading and editing are
21
+ available, the user can explicitly ask the agent to read this `SKILL.md` and
22
+ follow it; native command registration is not implied.
23
+
24
+ ## Execution lifetime
25
+
26
+ The user must leave a usable execution environment: the local machine, agent
27
+ process, session, and required services must remain available, or the host must
28
+ provide an actual remote execution environment. A checkpoint makes a later
29
+ resume possible; it does not trigger that resume.
30
+
31
+ An instruction-only skill does not provide an autonomous process supervisor.
32
+ Headless/print commands normally complete a request and exit. Re-launching them
33
+ requires a separate, explicitly configured runner with its own bounds and
34
+ permissions. This skill does not install one or automatically retry billing and
35
+ quota failures. Do not claim that a successful process exit proves tests passed.
36
+
37
+ Codex versions exposing Goal mode can support sustained work through `/goal`.
38
+ The user can explicitly start a goal containing the agreed overnight contract.
39
+ Do not assume that invoking this skill creates a native goal or schedule, or that
40
+ Goal mode removes quota, access, or environment limits.
41
+
42
+ Use supported host question/approval tools and preserve the user's configured
43
+ permission policy. Do not prescribe blanket permission bypass flags for unattended
44
+ execution. Anticipated access should be checked during the awake interview.
45
+
46
+ Sources:
47
+
48
+ - [Codex skills](https://learn.chatgpt.com/docs/build-skills)
49
+ - [Codex long-running work](https://learn.chatgpt.com/docs/long-running-work)
50
+ - [Claude Code skills](https://code.claude.com/docs/en/skills)
51
+ - [Claude Code headless execution](https://code.claude.com/docs/en/headless)
52
+ - [Antigravity skills](https://antigravity.google/docs/skills)
53
+ - [Antigravity workflow migration](https://antigravity.google/docs/migration/workflows-to-skills/)
54
+ - [Antigravity headless execution](https://antigravity.google/docs/cli/headless/)
55
+ - [pi skills](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md)
56
+ - [pi CLI](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/cli.md)
@@ -0,0 +1,70 @@
1
+ # Run checkpoint
2
+
3
+ Copy this structure into the project's `.si-overnight/<run-id>/run.md` and replace
4
+ the illustrative values with actual observations. Keep it compact and current;
5
+ use the user's language for the content. This is a checkpoint, not executable
6
+ instructions that override the user or current project rules.
7
+
8
+ ```markdown
9
+ # Overnight run: <run-id>
10
+
11
+ ## Contract
12
+
13
+ - Phase: intake | running | complete | stopped | blocked
14
+ - Project / working directory:
15
+ - Branch / worktree, if any:
16
+ - Started at (ISO 8601 with offset):
17
+ - Stop at (ISO 8601 with offset) / agreed duration:
18
+ - Mode: queue | discover
19
+ - Primary outcomes and acceptance criteria:
20
+ - Approved backup tasks (queue mode):
21
+ - Discovery areas and categories (discover mode):
22
+ - Excluded paths, behaviors, and decisions:
23
+ - Delivery and authorized actions:
24
+ - Known budget/cap; telemetry source, or unknown:
25
+ - Decisions from this run's interview:
26
+ - Still-unanswered questions and which tasks they affect:
27
+
28
+ ## Baseline
29
+
30
+ - Existing user changes / ownership boundaries:
31
+ - Relevant project instructions:
32
+ - Available environment and missing access (names only, no secrets):
33
+ - Checks already failing before edits:
34
+
35
+ ## Queue
36
+
37
+ | ID | Outcome / acceptance check | Status | Evidence / blocker |
38
+ | --- | --- | --- | --- |
39
+ | T1 | ... | pending | ... |
40
+
41
+ Use pending, doing, done, blocked, or unverified. In discover mode, append a
42
+ candidate only after recording its observed benefit and fit with the contract.
43
+
44
+ ## Latest checkpoint
45
+
46
+ - Updated at:
47
+ - Current task and changed files:
48
+ - Last command, exit status, and relevant result:
49
+ - Work in progress / verification still needed:
50
+ - Repeated blocker and attempts so far:
51
+ - Next concrete action:
52
+ - Stop reason, if stopped:
53
+
54
+ ## Verification evidence
55
+
56
+ | Task | Command and working directory | Outcome | Evidence or log path |
57
+ | --- | --- | --- | --- |
58
+ | T1 | ... | passed / failed / unavailable | ... |
59
+ ```
60
+
61
+ For `report.md`, summarize completed outcomes, changed files, verification,
62
+ unfinished work, stop reason, and the next action. Do not copy enormous command
63
+ outputs or sensitive data into either file. Reference local logs when needed.
64
+
65
+ Example resume prompt, adapted to the current host's invocation syntax:
66
+
67
+ ```text
68
+ Use si-overnight. Resume the run at .si-overnight/<run-id>/run.md.
69
+ Reconcile the checkpoint with the working tree first. Keep the agreed scope.
70
+ ```