opencode-windows-scheduler 0.0.0-stage → 1.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.
Files changed (183) hide show
  1. package/CHANGELOG.md +52 -0
  2. package/CROSS_PLATFORM.md +113 -0
  3. package/LICENSE +21 -0
  4. package/README.md +173 -2
  5. package/README.ru.md +131 -0
  6. package/ROADMAP-STRATEGY.md +217 -0
  7. package/ROADMAP.md +90 -0
  8. package/dist/core/analytics.d.ts +119 -0
  9. package/dist/core/analytics.d.ts.map +1 -0
  10. package/dist/core/analytics.js +265 -0
  11. package/dist/core/cron-to-schtasks.d.ts +20 -0
  12. package/dist/core/cron-to-schtasks.d.ts.map +1 -0
  13. package/dist/core/cron-to-schtasks.js +233 -0
  14. package/dist/core/dry-run.d.ts +44 -0
  15. package/dist/core/dry-run.d.ts.map +1 -0
  16. package/dist/core/dry-run.js +252 -0
  17. package/dist/core/file-watcher.d.ts +31 -0
  18. package/dist/core/file-watcher.d.ts.map +1 -0
  19. package/dist/core/file-watcher.js +128 -0
  20. package/dist/core/lock.d.ts +43 -0
  21. package/dist/core/lock.d.ts.map +1 -0
  22. package/dist/core/lock.js +118 -0
  23. package/dist/core/matrix.d.ts +167 -0
  24. package/dist/core/matrix.d.ts.map +1 -0
  25. package/dist/core/matrix.js +687 -0
  26. package/dist/core/ps-wrapper.d.ts +60 -0
  27. package/dist/core/ps-wrapper.d.ts.map +1 -0
  28. package/dist/core/ps-wrapper.js +538 -0
  29. package/dist/core/record-history.d.ts +14 -0
  30. package/dist/core/record-history.d.ts.map +1 -0
  31. package/dist/core/record-history.js +360 -0
  32. package/dist/core/retention.d.ts +29 -0
  33. package/dist/core/retention.d.ts.map +1 -0
  34. package/dist/core/retention.js +98 -0
  35. package/dist/core/scheduler/index.d.ts +20 -0
  36. package/dist/core/scheduler/index.d.ts.map +1 -0
  37. package/dist/core/scheduler/index.js +32 -0
  38. package/dist/core/scheduler/linux.d.ts +32 -0
  39. package/dist/core/scheduler/linux.d.ts.map +1 -0
  40. package/dist/core/scheduler/linux.js +115 -0
  41. package/dist/core/scheduler/logs.d.ts +11 -0
  42. package/dist/core/scheduler/logs.d.ts.map +1 -0
  43. package/dist/core/scheduler/logs.js +34 -0
  44. package/dist/core/scheduler/mac.d.ts +39 -0
  45. package/dist/core/scheduler/mac.d.ts.map +1 -0
  46. package/dist/core/scheduler/mac.js +175 -0
  47. package/dist/core/scheduler/posix.d.ts +40 -0
  48. package/dist/core/scheduler/posix.d.ts.map +1 -0
  49. package/dist/core/scheduler/posix.js +86 -0
  50. package/dist/core/scheduler/registry.d.ts +36 -0
  51. package/dist/core/scheduler/registry.d.ts.map +1 -0
  52. package/dist/core/scheduler/registry.js +56 -0
  53. package/dist/core/scheduler/types.d.ts +63 -0
  54. package/dist/core/scheduler/types.d.ts.map +1 -0
  55. package/dist/core/scheduler/types.js +1 -0
  56. package/dist/core/scheduler/windows.d.ts +47 -0
  57. package/dist/core/scheduler/windows.d.ts.map +1 -0
  58. package/dist/core/scheduler/windows.js +375 -0
  59. package/dist/core/wrappers/bash.d.ts +58 -0
  60. package/dist/core/wrappers/bash.d.ts.map +1 -0
  61. package/dist/core/wrappers/bash.js +223 -0
  62. package/dist/db/history-repo.d.ts +102 -0
  63. package/dist/db/history-repo.d.ts.map +1 -0
  64. package/dist/db/history-repo.js +215 -0
  65. package/dist/db/index.d.ts +47 -0
  66. package/dist/db/index.d.ts.map +1 -0
  67. package/dist/db/index.js +120 -0
  68. package/dist/db/metrics-repo.d.ts +43 -0
  69. package/dist/db/metrics-repo.d.ts.map +1 -0
  70. package/dist/db/metrics-repo.js +95 -0
  71. package/dist/db/migrate.d.ts +24 -0
  72. package/dist/db/migrate.d.ts.map +1 -0
  73. package/dist/db/migrate.js +237 -0
  74. package/dist/db/recovery.d.ts +11 -0
  75. package/dist/db/recovery.d.ts.map +1 -0
  76. package/dist/db/recovery.js +38 -0
  77. package/dist/db/schema.d.ts +24 -0
  78. package/dist/db/schema.d.ts.map +1 -0
  79. package/dist/db/schema.js +97 -0
  80. package/dist/db/settings-repo.d.ts +8 -0
  81. package/dist/db/settings-repo.d.ts.map +1 -0
  82. package/dist/db/settings-repo.js +27 -0
  83. package/dist/db/tasks-repo.d.ts +26 -0
  84. package/dist/db/tasks-repo.d.ts.map +1 -0
  85. package/dist/db/tasks-repo.js +120 -0
  86. package/dist/db/templates-repo.d.ts +17 -0
  87. package/dist/db/templates-repo.d.ts.map +1 -0
  88. package/dist/db/templates-repo.js +57 -0
  89. package/dist/history.d.ts +53 -0
  90. package/dist/history.d.ts.map +1 -0
  91. package/dist/history.js +57 -0
  92. package/dist/index.d.ts +156 -0
  93. package/dist/index.d.ts.map +1 -0
  94. package/dist/index.js +2159 -0
  95. package/dist/notifications.d.ts +45 -0
  96. package/dist/notifications.d.ts.map +1 -0
  97. package/dist/notifications.js +135 -0
  98. package/dist/rpc.d.ts +2186 -0
  99. package/dist/rpc.d.ts.map +1 -0
  100. package/dist/rpc.js +924 -0
  101. package/dist/schtasks.d.ts +32 -0
  102. package/dist/schtasks.d.ts.map +1 -0
  103. package/dist/schtasks.js +45 -0
  104. package/dist/server.d.ts +106 -0
  105. package/dist/server.d.ts.map +1 -0
  106. package/dist/server.js +1668 -0
  107. package/dist/settings.d.ts +66 -0
  108. package/dist/settings.d.ts.map +1 -0
  109. package/dist/settings.js +137 -0
  110. package/dist/shared/jobs-view.d.ts +21 -0
  111. package/dist/shared/jobs-view.d.ts.map +1 -0
  112. package/dist/shared/jobs-view.js +28 -0
  113. package/dist/skill.d.ts +15 -0
  114. package/dist/skill.d.ts.map +1 -0
  115. package/dist/skill.js +93 -0
  116. package/dist/task-transfer.d.ts +176 -0
  117. package/dist/task-transfer.d.ts.map +1 -0
  118. package/dist/task-transfer.js +442 -0
  119. package/dist/templates.d.ts +57 -0
  120. package/dist/templates.d.ts.map +1 -0
  121. package/dist/templates.js +16 -0
  122. package/dist/types.d.ts +78 -0
  123. package/dist/types.d.ts.map +1 -0
  124. package/dist/types.js +88 -0
  125. package/dist/version.d.ts +8 -0
  126. package/dist/version.d.ts.map +1 -0
  127. package/dist/version.js +27 -0
  128. package/dist/workspaces.d.ts +55 -0
  129. package/dist/workspaces.d.ts.map +1 -0
  130. package/dist/workspaces.js +183 -0
  131. package/docs/ARCHITECTURE.md +314 -0
  132. package/docs/FEATURES.md +300 -0
  133. package/docs/MIGRATION.md +266 -0
  134. package/docs/dashboard.png +0 -0
  135. package/gui-experimental.cjs +2 -0
  136. package/index.js +1 -0
  137. package/package.json +94 -4
  138. package/scripts/demo-dashboard.mjs +199 -0
  139. package/skills/scheduled-job-best-practices/SKILL.md +155 -0
  140. package/skills/scheduled-job-best-practices/references/recipes.md +123 -0
  141. package/src/core/analytics.ts +378 -0
  142. package/src/core/cron-to-schtasks.ts +269 -0
  143. package/src/core/dry-run.ts +315 -0
  144. package/src/core/file-watcher.ts +171 -0
  145. package/src/core/lock.ts +134 -0
  146. package/src/core/matrix.ts +907 -0
  147. package/src/core/ps-wrapper.ts +572 -0
  148. package/src/core/record-history.ts +493 -0
  149. package/src/core/retention.ts +141 -0
  150. package/src/core/scheduler/index.ts +44 -0
  151. package/src/core/scheduler/linux.ts +125 -0
  152. package/src/core/scheduler/logs.ts +37 -0
  153. package/src/core/scheduler/mac.ts +222 -0
  154. package/src/core/scheduler/posix.ts +111 -0
  155. package/src/core/scheduler/registry.ts +93 -0
  156. package/src/core/scheduler/types.ts +67 -0
  157. package/src/core/scheduler/windows.ts +469 -0
  158. package/src/core/wrappers/bash.ts +282 -0
  159. package/src/db/history-repo.ts +396 -0
  160. package/src/db/index.ts +166 -0
  161. package/src/db/metrics-repo.ts +158 -0
  162. package/src/db/migrate.ts +322 -0
  163. package/src/db/recovery.ts +46 -0
  164. package/src/db/schema.ts +109 -0
  165. package/src/db/settings-repo.ts +31 -0
  166. package/src/db/tasks-repo.ts +162 -0
  167. package/src/db/templates-repo.ts +77 -0
  168. package/src/gui.tsx +2868 -0
  169. package/src/history.ts +107 -0
  170. package/src/index.ts +2768 -0
  171. package/src/notifications.ts +174 -0
  172. package/src/rpc.ts +999 -0
  173. package/src/schtasks.ts +75 -0
  174. package/src/server.ts +1879 -0
  175. package/src/settings.ts +228 -0
  176. package/src/shared/jobs-view.ts +38 -0
  177. package/src/skill.ts +113 -0
  178. package/src/task-transfer.ts +648 -0
  179. package/src/templates.ts +67 -0
  180. package/src/tui.tsx +46 -0
  181. package/src/types.ts +145 -0
  182. package/src/version.ts +27 -0
  183. package/src/workspaces.ts +236 -0
package/package.json CHANGED
@@ -1,6 +1,96 @@
1
1
  {
2
2
  "name": "opencode-windows-scheduler",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.1.0",
4
+ "description": "Local-first scheduling and orchestration for OpenCode v2 agent jobs: cron, DAG pipelines, matrix fan-out, quality gates and observability. Free and open source (MIT).",
5
+ "license": "MIT",
6
+ "author": "opencode-windows-scheduler contributors",
7
+ "homepage": "https://github.com/DeadSno/opencode-windows-scheduler#readme",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/DeadSno/opencode-windows-scheduler.git"
11
+ },
12
+ "bugs": {
13
+ "url": "https://github.com/DeadSno/opencode-windows-scheduler/issues"
14
+ },
15
+ "keywords": [
16
+ "opencode",
17
+ "opencode-plugin",
18
+ "scheduler",
19
+ "cron",
20
+ "task-scheduler",
21
+ "windows-scheduler",
22
+ "launchd",
23
+ "systemd",
24
+ "ai-agents",
25
+ "automation",
26
+ "matrix-builds",
27
+ "dag"
28
+ ],
29
+ "main": "dist/index.js",
30
+ "types": "dist/index.d.ts",
31
+ "type": "module",
32
+ "exports": {
33
+ ".": "./src/index.ts",
34
+ "./tui": "./src/tui.tsx",
35
+ "./gui-experimental": "./gui-experimental.cjs"
36
+ },
37
+ "files": [
38
+ "dist",
39
+ "src",
40
+ "index.js",
41
+ "gui-experimental.cjs",
42
+ "skills",
43
+ "scripts",
44
+ "docs",
45
+ "README.md",
46
+ "README.ru.md",
47
+ "LICENSE",
48
+ "CHANGELOG.md",
49
+ "CROSS_PLATFORM.md",
50
+ "ROADMAP.md",
51
+ "ROADMAP-STRATEGY.md"
52
+ ],
53
+ "engines": {
54
+ "node": ">=20"
55
+ },
56
+ "publishConfig": {
57
+ "access": "public"
58
+ },
59
+ "scripts": {
60
+ "build": "tsc",
61
+ "build:gui": "vite build",
62
+ "demo": "node scripts/demo-dashboard.mjs",
63
+ "prepare": "npm run build",
64
+ "prepublishOnly": "npm run build && npm run build:gui",
65
+ "test": "node test-sqlite.mjs && node test-crash-recovery.mjs && node test-workspaces.mjs && node test-role-scoped.mjs && node test-dry-run.mjs && node test-matrix.mjs && node test-matrix-lifecycle.mjs && node test-matrix-sync.mjs && node test-retention.mjs && node test-metrics.mjs && node test-agent-tools.mjs && node test-skill.mjs && node test-docs.mjs",
66
+ "test:sqlite": "node test-sqlite.mjs",
67
+ "test:crash": "node test-crash-recovery.mjs",
68
+ "test:workspaces": "node test-workspaces.mjs",
69
+ "test:role": "node test-role-scoped.mjs",
70
+ "test:dry-run": "node test-dry-run.mjs",
71
+ "test:matrix": "node test-matrix.mjs",
72
+ "test:matrix-lifecycle": "node test-matrix-lifecycle.mjs",
73
+ "test:matrix-sync": "node test-matrix-sync.mjs",
74
+ "test:retention": "node test-retention.mjs",
75
+ "test:metrics": "node test-metrics.mjs",
76
+ "test:agent": "node test-agent-tools.mjs",
77
+ "test:skill": "node test-skill.mjs",
78
+ "test:docs": "node test-docs.mjs"
79
+ },
80
+ "dependencies": {
81
+ "@opencode/plugin": "^2.2.7",
82
+ "@opencode/schema": "^2.2.7",
83
+ "chokidar": "^6.0.0",
84
+ "iconv-lite": "^0.7.3",
85
+ "zod": "^4.6.7"
86
+ },
87
+ "devDependencies": {
88
+ "@opentui/core": ">=0.8.1",
89
+ "@opentui/solid": ">=0.8.1",
90
+ "@types/node": "^20.19.43",
91
+ "solid-js": "^1.9.0",
92
+ "typescript": "^5.9.3",
93
+ "vite": "^7.0.0",
94
+ "vite-plugin-solid": "^2.11.0"
95
+ }
96
+ }
@@ -0,0 +1,199 @@
1
+ /**
2
+ * Demo dashboard: seeds a temporary database with a realistic job set
3
+ * (cron jobs, a DAG chain, a matrix with clones, a file trigger) and
4
+ * starts the local web dashboard.
5
+ *
6
+ * Usage: node scripts/demo-dashboard.mjs [--port 3782]
7
+ *
8
+ * The demo uses a temporary APPDATA directory, so it never touches your
9
+ * real jobs, history or settings.
10
+ */
11
+ import fs from "node:fs";
12
+ import os from "node:os";
13
+ import path from "node:path";
14
+
15
+ const portArgIndex = process.argv.indexOf("--port");
16
+ const preferredPort =
17
+ portArgIndex >= 0 && process.argv[portArgIndex + 1]
18
+ ? Number(process.argv[portArgIndex + 1])
19
+ : 3782;
20
+
21
+ const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ws-scheduler-demo-"));
22
+ process.env.APPDATA = tempRoot;
23
+
24
+ for (const dir of ["frontend", "backend", "mobile", "docs", "infra"]) {
25
+ fs.mkdirSync(path.join(tempRoot, "repos", dir), { recursive: true });
26
+ }
27
+
28
+ const { initDb, closeDb } = await import("../dist/db/index.js");
29
+ const { saveTask, listTasks } = await import("../dist/db/tasks-repo.js");
30
+ const { recordRun, getHistory } = await import("../dist/db/history-repo.js");
31
+ const { addWorkspace } = await import("../dist/workspaces.js");
32
+ const { aggregateMatrixResults } = await import("../dist/core/matrix.js");
33
+ const { startDashboardServer } = await import("../dist/server.js");
34
+
35
+ initDb();
36
+
37
+ const frontend = addWorkspace({ path: path.join(tempRoot, "repos", "frontend"), name: "Frontend" });
38
+ const backend = addWorkspace({ path: path.join(tempRoot, "repos", "backend"), name: "Backend" });
39
+ const mobile = addWorkspace({ path: path.join(tempRoot, "repos", "mobile"), name: "Mobile" });
40
+ const docs = addWorkspace({ path: path.join(tempRoot, "repos", "docs"), name: "Docs" });
41
+ const infra = addWorkspace({ path: path.join(tempRoot, "repos", "infra"), name: "Infra" });
42
+
43
+ const tasks = [
44
+ {
45
+ name: "nightly-deps",
46
+ schedule: "0 3 * * *",
47
+ prompt: "Обнови зависимости, прогони тесты и приложи отчёт.",
48
+ model: "anthropic/claude-sonnet-4",
49
+ priority: 7,
50
+ qualityGate: "npm test",
51
+ workspaceId: backend.id,
52
+ },
53
+ {
54
+ name: "deploy",
55
+ schedule: "0 4 * * *",
56
+ prompt: "Собери, протестируй и задеплой сервис.",
57
+ model: "anthropic/claude-sonnet-4",
58
+ priority: 9,
59
+ matrix: {
60
+ workspaceIds: [frontend.id, backend.id, mobile.id],
61
+ strategy: "parallel",
62
+ failureMode: "continue",
63
+ aggregation: "summary",
64
+ concurrency: 2,
65
+ createAggregator: true,
66
+ overrides: { [mobile.id]: { qualityGate: "npm run test:mobile" } },
67
+ },
68
+ isMatrixParent: true,
69
+ },
70
+ {
71
+ name: "deploy-matrix-Frontend",
72
+ schedule: "0 4 * * *",
73
+ prompt: "Собери, протестируй и задеплой сервис.",
74
+ workspaceId: frontend.id,
75
+ matrixParentId: "deploy",
76
+ triggerType: "file",
77
+ qualityGate: "npm test",
78
+ },
79
+ {
80
+ name: "deploy-matrix-Backend",
81
+ schedule: "0 4 * * *",
82
+ prompt: "Собери, протестируй и задеплой сервис.",
83
+ workspaceId: backend.id,
84
+ matrixParentId: "deploy",
85
+ triggerType: "file",
86
+ qualityGate: "npm test",
87
+ },
88
+ {
89
+ name: "deploy-matrix-Mobile",
90
+ schedule: "0 4 * * *",
91
+ prompt: "Собери, протестируй и задеплой сервис.",
92
+ workspaceId: mobile.id,
93
+ matrixParentId: "deploy",
94
+ triggerType: "file",
95
+ qualityGate: "npm run test:mobile",
96
+ },
97
+ {
98
+ name: "smoke-tests",
99
+ schedule: "30 4 * * *",
100
+ prompt: "Прогони smoke-тесты после деплоя и напиши в чат при падении.",
101
+ dependsOn: ["deploy"],
102
+ priority: 10,
103
+ workspaceId: infra.id,
104
+ },
105
+ {
106
+ name: "docs-sync",
107
+ schedule: "",
108
+ prompt: "Перегенерируй документацию по OpenAPI-схеме.",
109
+ triggerType: "file",
110
+ watchPath: "C:\\projects\\docs\\openapi.yaml",
111
+ workspaceId: docs.id,
112
+ },
113
+ {
114
+ name: "weekly-report",
115
+ schedule: "0 9 * * 1",
116
+ prompt: "Собери недельный отчёт: PR, инциденты, стоимость токенов.",
117
+ model: "openai/gpt-5.1",
118
+ priority: 4,
119
+ },
120
+ ];
121
+
122
+ for (const task of tasks) saveTask(task);
123
+
124
+ function run(name, status, ageMinutes, durationMs, error = null, extra = {}) {
125
+ const startedAt = new Date(Date.now() - ageMinutes * 60_000).toISOString();
126
+ recordRun(
127
+ name,
128
+ status,
129
+ startedAt,
130
+ durationMs,
131
+ error,
132
+ undefined,
133
+ extra.tokens ?? 4200,
134
+ extra.costUsd ?? 0.012,
135
+ extra.model ?? "anthropic/claude-sonnet-4",
136
+ extra.preFlight ?? "skipped",
137
+ extra.postFlight ?? "skipped"
138
+ );
139
+ }
140
+
141
+ run("deploy-matrix-Frontend", "success", 95, 74_000, null, { tokens: 18_400 });
142
+ run("deploy-matrix-Backend", "success", 94, 128_000, null, { tokens: 26_800 });
143
+ run("deploy-matrix-Mobile", "error", 93, 46_000, "Gradle build failed: SDK 35 not installed", { tokens: 9_200 });
144
+ run("deploy", "partial", 92, 0, "1 из 3 клонов завершился с ошибкой");
145
+ run("smoke-tests", "success", 88, 31_000, null, { preFlight: "success", postFlight: "success" });
146
+ run("nightly-deps", "success", 60, 212_000, null, { tokens: 44_200, costUsd: 0.09 });
147
+ run("nightly-deps", "error", 24 * 60 + 60, 96_000, "Quality Gate failed: npm test exit code 1", { preFlight: "success" });
148
+ run("weekly-report", "success", 2 * 24 * 60, 155_000, null, { tokens: 61_300, costUsd: 0.14, model: "openai/gpt-5.1" });
149
+ run("docs-sync", "success", 300, 22_000, null, { tokens: 7_400 });
150
+
151
+ const history = getHistory(null, 500);
152
+ const latestStatus = (name) => {
153
+ const record = getHistory(name, 1)[0];
154
+ return record ? record.status : "pending";
155
+ };
156
+
157
+ function taskView(definition) {
158
+ const aggregate = definition.isMatrixParent ? aggregateMatrixResults(definition.name) : null;
159
+ const status = aggregate ? aggregate.status : latestStatus(definition.name);
160
+ return {
161
+ ...definition,
162
+ status,
163
+ nextRun: definition.triggerType === "file" ? null : "сегодня, 03:00",
164
+ matrixSummary: aggregate
165
+ ? {
166
+ status: aggregate.status,
167
+ message: aggregate.message,
168
+ successCount: aggregate.successCount,
169
+ errorCount: aggregate.errorCount,
170
+ pendingCount: aggregate.pendingCount,
171
+ totalCount: aggregate.totalCount,
172
+ }
173
+ : undefined,
174
+ metrics: {
175
+ total: history.filter((h) => h.taskName === definition.name).length,
176
+ success: history.filter((h) => h.taskName === definition.name && h.status === "success").length,
177
+ error: history.filter((h) => h.taskName === definition.name && h.status === "error").length,
178
+ },
179
+ };
180
+ }
181
+
182
+ const deps = {
183
+ getTasks: async () => listTasks().map(taskView),
184
+ runTask: async () => ({ alreadyRunning: false }),
185
+ deleteTask: async () => {},
186
+ };
187
+
188
+ const started = await startDashboardServer(deps, { preferred: preferredPort, fallback: preferredPort + 1000 });
189
+ console.log(`Demo dashboard: http://127.0.0.1:${started.port}`);
190
+ console.log("Press Ctrl+C to stop.");
191
+
192
+ const shutdown = () => {
193
+ try {
194
+ closeDb();
195
+ } catch {}
196
+ process.exit(0);
197
+ };
198
+ process.on("SIGINT", shutdown);
199
+ process.on("SIGTERM", shutdown);
@@ -0,0 +1,155 @@
1
+ ---
2
+ name: Scheduled Job Best Practices
3
+ description: Use when the user wants recurring or event-driven automation (cron, file changes, MCP events), multi-repository fan-out, or agent pipelines. Covers safe defaults, prompt design, Quality Gates, matrix builds, DAG dependencies and post-incident diagnosis with the scheduler tools.
4
+ ---
5
+
6
+ # Scheduled Job Best Practices
7
+
8
+ Use this skill whenever the user asks to automate something on a schedule, on a file change,
9
+ on an MCP event, or as a multi-step pipeline. The goal is automation that is safe, cheap,
10
+ idempotent and debuggable a month later.
11
+
12
+ Respond in the user's language. This document is in English for portability.
13
+
14
+ ## 1. Start by looking at what already exists
15
+
16
+ Call `list_tasks` before creating anything. If a similar task exists, prefer `update_task`
17
+ (partial update, matrix clones are synchronized) over delete + create. Automation that
18
+ silently duplicates work is worse than no automation.
19
+
20
+ Check the returned fields: schedule, trigger, working directory, model, dependencies, matrix
21
+ summary, last run.
22
+
23
+ ## 2. Choose the simplest shape that works
24
+
25
+ | User need | Shape | Why |
26
+ | --- | --- | --- |
27
+ | "Every morning / every hour / weekly" | `schedule_task` with cron | Durable OS-level schedule, survives restarts |
28
+ | "When this file changes" | `triggerType: "file"` + `watchPath` | No polling; the watcher debounces bursts |
29
+ | "When my MCP server reports an event" | `triggerType: "mcp-event"` + `mcpEvent` | Event-driven, no wasted runs |
30
+ | "Same work in N repositories" | `matrix.workspaceIds` | One definition, isolated clones, aggregated status |
31
+ | "A then B then C" | `dependsOn` + `nextTaskOnSuccess` / `nextTaskOnError` | Explicit DAG, failures stop the line |
32
+ | "Try again if it fails" | `retryCount` + `retryDelay` | Handles flaky networks and rate limits |
33
+
34
+ Do not use a 5-field cron for a one-off reminder. Do not build a pipeline with chained
35
+ prompts inside a single task when `dependsOn` exists: a failed step would be invisible.
36
+
37
+ ## 3. Write prompts that survive without context
38
+
39
+ Every run starts from a clean slate: no chat history, no memory of the previous run, nobody
40
+ to answer questions. A good prompt states:
41
+
42
+ 1. **Goal** — the outcome in one sentence.
43
+ 2. **Scope** — exact paths, repositories or modules to touch.
44
+ 3. **Constraints** — what must not change, tool limits, style rules.
45
+ 4. **Verification** — the command that proves success (this is the Quality Gate).
46
+ 5. **Output** — where to write the report and what to include (counts, links, failures).
47
+
48
+ Bad: `Check the repo and fix problems.`
49
+ Good: `In ./services/api run the test suite. If tests fail, fix only failures caused by
50
+ type errors, then re-run until green or 20 minutes elapse. Write a summary to
51
+ reports/nightly-api.md with the failing test names and the commit you started from.`
52
+
53
+ Never ask the agent to "ask the user" in a scheduled prompt — nobody is there. If a decision
54
+ is genuinely ambiguous, tell it to stop and write the question into the report.
55
+
56
+ ## 4. Safety defaults
57
+
58
+ - **Least privilege**: set `allowedTools` / `deniedTools`. Read-only monitoring jobs should
59
+ not be allowed to `write` or run destructive shell commands.
60
+ - **Timeout**: always set `timeoutSeconds` for jobs that call networks or models. Default
61
+ timeouts are a safety net, not a plan.
62
+ - **Quality Gate**: pass `qualityGate` whenever a machine-checkable success criterion exists
63
+ (`npm test`, `pytest -q`, `curl -f`, `git diff --quiet`). A run that "looks successful" is
64
+ not evidence.
65
+ - **No secrets in prompts**: prompts are stored in plain text and appear in logs. Reference
66
+ environment variables or files instead.
67
+ - **Idempotent by design**: a job may run twice (retry, catch-up after downtime, manual run).
68
+ Prefer "ensure state" over "append" — e.g. rewrite a report file rather than appending.
69
+ - **Blast radius**: avoid `git push --force`, `rm -rf`, mass dependency upgrades or
70
+ production deploys without a Quality Gate and a manual `run_task_now` smoke test first.
71
+
72
+ ## 5. Matrix builds (multi-repository)
73
+
74
+ Use a matrix when the same prompt must run in several workspaces:
75
+
76
+ - `matrix.workspaceIds` — the repositories, referenced by workspace ID (call
77
+ `manage_workspaces` with `action: "list"` to discover them).
78
+ - `matrix.strategy` — `parallel` (default) or `sequential`.
79
+ - `matrix.failureMode` — `continue` (default, aggregated as `partial`) or `stop`.
80
+ - `matrix.concurrency` — cap simultaneous clones; respect machine and API limits. Keep it
81
+ small (2–4) unless the work is purely local.
82
+ - `matrix.overrides` — per-workspace prompt/model/qualityGate/hooks when one repository
83
+ differs (different package manager, stricter gate).
84
+ - `matrix.createAggregator` — creates a follow-up task that runs once after all clones.
85
+
86
+ Rules of thumb:
87
+
88
+ - The matrix parent never runs itself; only its clones do. Do not set `workspaceId` on the
89
+ parent — it is a validation error to combine it with `matrix`.
90
+ - A dependency on a matrix parent waits for **all** clones to succeed.
91
+ - If clones are inherently independent (linting, docs), `failureMode: "continue"` gives a
92
+ useful aggregate. If one failure makes the rest pointless (deploy), use `"stop"`.
93
+ - After editing a matrix parent with `update_task`, clones are diffed and synchronized;
94
+ running clones are left alone.
95
+
96
+ ## 6. DAG rules
97
+
98
+ - `dependsOn` lists task names that must have succeeded (their latest run) before this task
99
+ starts.
100
+ - `nextTaskOnSuccess` / `nextTaskOnError` chain a single follow-up run; use them for
101
+ notifications and rollbacks.
102
+ - Keep chains short and named by intent (`deploy` → `smoke-tests` → `notify-release`).
103
+ - Cycles and self-dependencies are rejected; if a chain grows past 4–5 nodes, consider one
104
+ task with an explicit internal checklist instead.
105
+
106
+ ## 7. Validate before you commit
107
+
108
+ 1. `dry_run` with the task name (or without a name for the whole pipeline): shows order,
109
+ dependencies, matrix fan-out, estimated duration and cost. Nothing is executed.
110
+ 2. Create the task with `schedule_task`.
111
+ 3. `run_task_now` once and inspect `get_history` / `get_task_logs`. A schedule that has never
112
+ run successfully is a liability.
113
+ 4. Only then tell the user it is ready, and state the cron expression in plain language
114
+ ("every weekday at 09:00 local time").
115
+
116
+ ## 8. Diagnosing failures later
117
+
118
+ - `get_history` filtered by `taskName` and `status` — statuses: `running`, `success`, `error`,
119
+ `timeout`, `partial`.
120
+ - `get_task_logs` with `lines` — tail of the wrapper log; use it to distinguish model failure,
121
+ Quality Gate failure, timeout and lock-skip.
122
+ - Matrix problems: `matrix_control` with `action: "results"` for counters, `action: "cancel"`
123
+ to stop pending clones, `action: "cleanup"` to remove clones whose parent is gone.
124
+ - A timeout usually means the prompt is too broad. Split it or raise `timeoutSeconds`
125
+ deliberately.
126
+ - A skipped run (`already running`) means the previous run overran its interval; shorten the
127
+ prompt, raise the interval, or set a smaller timeout.
128
+
129
+ ## 9. Anti-patterns
130
+
131
+ | Anti-pattern | Consequence | Fix |
132
+ | --- | --- | --- |
133
+ | `* * * * *` with a heavy prompt | Runs overlap, lock-skips, cost spikes | Realistic interval + timeout |
134
+ | Prompt depending on chat context | Nonsense output at 03:00 | Self-contained prompt with paths |
135
+ | No Quality Gate on a "fixer" job | Broken code reported as success | `qualityGate: "npm test"` |
136
+ | Matrix with 20 workspaces, no concurrency cap | Machine and API saturation | `matrix.concurrency: 2–4` |
137
+ | Secrets inside the prompt | Leak into DB, logs and dashboard | Env vars or files |
138
+ | Deleting a matrix parent's clone by hand | Orphaned history, broken aggregate | `update_task` on the parent |
139
+ | Creating a duplicate instead of updating | Double runs, conflicting writes | `update_task` |
140
+
141
+ ## 10. Final checklist
142
+
143
+ Before saying the job is done, confirm:
144
+
145
+ - [ ] `list_tasks` checked; no duplicate exists.
146
+ - [ ] Trigger type matches the need (cron / file / MCP event).
147
+ - [ ] Prompt states goal, scope, constraints, verification and output.
148
+ - [ ] `timeoutSeconds` set; `qualityGate` set when checkable.
149
+ - [ ] `allowedTools` / `deniedTools` follow least privilege.
150
+ - [ ] Matrix: workspaces correct, concurrency capped, failure mode justified.
151
+ - [ ] `dry_run` reviewed.
152
+ - [ ] One successful `run_task_now` with clean `get_history`.
153
+ - [ ] Cron expressed in words for the user.
154
+
155
+ See `references/recipes.md` for complete examples.
@@ -0,0 +1,123 @@
1
+ # Recipes
2
+
3
+ Complete, copy-ready examples. Values in `<angle brackets>` are placeholders.
4
+
5
+ ## 1. Nightly dependency and test run
6
+
7
+ ```json
8
+ {
9
+ "name": "nightly-deps",
10
+ "schedule": "0 2 * * *",
11
+ "prompt": "In the repository root run `npm outdated` and `npm audit --omit=dev`. Do not upgrade majors. Apply only patch/minor security fixes, run `npm test` after each upgrade, and revert a package if tests fail. Write a summary to reports/nightly-deps.md: upgraded packages with versions, rejected upgrades and why, final test result.",
12
+ "workingDirectory": "<absolute path to repository>",
13
+ "timeoutSeconds": 2400,
14
+ "qualityGate": "npm test",
15
+ "retryCount": 1,
16
+ "retryDelay": 300,
17
+ "allowedTools": ["read", "write", "bash"],
18
+ "deniedTools": ["webfetch"]
19
+ }
20
+ ```
21
+
22
+ Why: bounded scope (no majors), machine-checkable gate, report for the morning.
23
+
24
+ ## 2. Weekday morning digest
25
+
26
+ ```json
27
+ {
28
+ "name": "morning-digest",
29
+ "schedule": "0 9 * * 1-5",
30
+ "prompt": "Collect: commits to main since the last working day (`git log --since=yesterday`), open pull requests (`gh pr list --state open`), and failed CI runs (`gh run list --status failure --limit 10`). Write a Russian-language digest to reports/digest-<date>.md with sections Commits / PRs / CI failures. If a command is unavailable, record that instead of failing.",
31
+ "workingDirectory": "<absolute path to repository>",
32
+ "timeoutSeconds": 900,
33
+ "allowedTools": ["read", "bash"]
34
+ }
35
+ ```
36
+
37
+ Why: read-only, tolerant of missing CLIs, output is the product.
38
+
39
+ ## 3. Regenerate a client when the API contract changes
40
+
41
+ ```json
42
+ {
43
+ "name": "regenerate-api-client",
44
+ "prompt": "openapi.yaml changed. Run `npm run generate:client`, then `npm run typecheck` and `npm test -- --runInBand`. If generation fails because of a schema error, do not edit the schema: write the failing path and reason to reports/api-client-error.md and stop. On success write the list of regenerated files to reports/api-client.md.",
45
+ "triggerType": "file",
46
+ "watchPath": "<absolute path to openapi.yaml>",
47
+ "workingDirectory": "<absolute path to client repository>",
48
+ "timeoutSeconds": 1200,
49
+ "qualityGate": "npm run typecheck",
50
+ "allowedTools": ["read", "write", "bash"]
51
+ }
52
+ ```
53
+
54
+ Why: event-driven instead of polling, explicit "do not touch the contract" constraint.
55
+
56
+ ## 4. Multi-repository lint and test matrix
57
+
58
+ ```json
59
+ {
60
+ "name": "repo-health",
61
+ "schedule": "0 6 * * 1",
62
+ "prompt": "Run the project's lint and test commands. Write a short report to reports/weekly-health.md with the command output summary. Fix nothing; only report.",
63
+ "timeoutSeconds": 1800,
64
+ "matrix": {
65
+ "workspaceIds": ["<frontend-id>", "<backend-id>", "<mobile-id>"],
66
+ "strategy": "parallel",
67
+ "failureMode": "continue",
68
+ "concurrency": 2,
69
+ "aggregation": "summary",
70
+ "overrides": {
71
+ "<mobile-id>": {
72
+ "qualityGate": "flutter test",
73
+ "prompt": "Run `flutter analyze` and `flutter test`. Write the summary to reports/weekly-health.md. Fix nothing."
74
+ }
75
+ }
76
+ },
77
+ "allowedTools": ["read", "bash"]
78
+ }
79
+ ```
80
+
81
+ Why: one definition, per-repository deviation in `overrides`, capped parallelism, partial
82
+ results still actionable.
83
+
84
+ ## 5. Deploy pipeline with gate and rollback
85
+
86
+ Tasks, in order:
87
+
88
+ 1. `deploy` — `schedule: "0 3 * * *"`, prompt builds and deploys, `qualityGate: "npm run smoke"`,
89
+ `timeoutSeconds: 1800`, `nextTaskOnSuccess: "notify-release"`,
90
+ `nextTaskOnError: "rollback"`.
91
+ 2. `notify-release` — posts a release message, `timeoutSeconds: 300`, read-only tools.
92
+ 3. `rollback` — restores the previous release, `qualityGate: "npm run smoke"`,
93
+ `triggerType: "file"` (started only by the chain), `timeoutSeconds: 1200`.
94
+
95
+ Verify the chain with `dry_run` for `deploy`: the output must show `deploy → notify-release`
96
+ and the error branch.
97
+
98
+ ## 6. Weekly cleanup of stale branches
99
+
100
+ ```json
101
+ {
102
+ "name": "stale-branches",
103
+ "schedule": "0 10 * * 5",
104
+ "prompt": "List merged remote branches older than 30 days (`git branch -r --merged main`). Do not delete `main`, `develop`, `release/*` or branches whose last commit is younger than 30 days. Delete the rest with `git push origin --delete`. Write the deleted and kept branches to reports/stale-branches.md with reasons.",
105
+ "workingDirectory": "<absolute path to repository>",
106
+ "timeoutSeconds": 600,
107
+ "qualityGate": "git diff --quiet",
108
+ "allowedTools": ["read", "bash"],
109
+ "deniedTools": ["write"]
110
+ }
111
+ ```
112
+
113
+ Why: explicit protected list, dry-run first, auditable report. Ask the user to run
114
+ `run_task_now` and confirm the report before enabling the schedule.
115
+
116
+ ## 7. Diagnosing a `partial` matrix
117
+
118
+ 1. `matrix_control` with `action: "results"` and the parent name → counters and the failing clones.
119
+ 2. `get_history` with `taskName: "<parent>-matrix-<workspace>"` and `status: "error"`.
120
+ 3. `get_task_logs` for that clone, `lines: 120`.
121
+ 4. Fix the cause (`update_task` on the parent for a definition bug, or the repository itself).
122
+ 5. Re-run only the failed clone with `run_task_now`, then confirm the aggregate becomes
123
+ `success`.