kaizen-agent 1.69.1 → 1.71.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 +2 -2
- package/cli/annotate-proxy.ts +135 -0
- package/cli/annotate.ts +86 -0
- package/cli/automations.ts +10 -3
- package/cli/browser.ts +1 -1
- package/cli/chat.ts +9 -1
- package/cli/chatgpt.ts +2 -1
- package/cli/docs.ts +1 -1
- package/cli/google.ts +2 -1
- package/cli/handoff.ts +1 -1
- package/cli/install.ts +28 -8
- package/cli/knowledge.ts +1 -1
- package/cli/notes.ts +10 -1
- package/cli/pty.ts +21 -0
- package/cli/settings.ts +5 -1
- package/cli/sources.ts +3 -2
- package/cli/state.ts +43 -5
- package/cli/versions.ts +1 -1
- package/cli/video.ts +1 -1
- package/cli/web.ts +137 -35
- package/cli/workers.ts +20 -7
- package/cli/worktree.ts +55 -15
- package/package.json +1 -1
- package/skills/kaizen/SKILL.md +12 -8
- package/skills/kaizen/config.default.yml +18 -2
- package/skills/kaizen/settings.md +3 -1
- package/skills/kaizen/spec-build.md +13 -2
- package/skills/kaizen/spec-main.md +2 -0
- package/skills/kaizen-help/SKILL.md +1 -0
- package/skills/media/kaizen-game/SKILL.md +96 -0
- package/skills/media/kaizen-game/assets/gdd.css +12 -0
- package/skills/media/kaizen-game/references/build.md +81 -0
- package/skills/media/kaizen-game/references/content.md +32 -0
- package/skills/media/kaizen-game/references/design.md +81 -0
- package/skills/media/kaizen-game/references/ship.md +34 -0
- package/skills/media/kaizen-game/references/verify.md +33 -0
- package/skills/media/kaizen-game/scripts/check.sh +13 -0
- package/skills/media/kaizen-game/scripts/frames.mjs +34 -0
- package/skills/media/kaizen-game/scripts/gdd-pdf.mjs +19 -0
- package/skills/media/kaizen-game/scripts/pw.mjs +18 -0
- package/skills/media/kaizen-game/scripts/serve.mjs +53 -0
- package/skills/media/kaizen-game/scripts/serve.test.mjs +18 -0
- package/skills/media/kaizen-game/scripts/setup.sh +9 -0
- package/skills/media/kaizen-game/scripts/smoke.mjs +40 -0
- package/skills/media/kaizen-game/skill.json +1 -0
- package/web/annotate.js +382 -0
- package/web/board/annotate-lib.ts +15 -0
- package/web/board/annotate.ts +181 -0
- package/web/board/badge.ts +12 -0
- package/web/board/icebox.ts +6 -3
- package/web/board/markdown.ts +7 -2
- package/web/board/run-view.ts +83 -9
- package/web/board/settings-orchestration.ts +1 -1
- package/web/board/settings-pages.ts +1 -0
- package/web/board/settings-skills.ts +1 -0
- package/web/board/settings.ts +2 -2
- package/web/board.html +5 -3
- package/web/board.js +119 -119
- package/web/notebook.js +23 -23
- package/web/term.js +48 -48
- package/web/term.ts +16 -4
- package/web/video.js +25 -25
package/cli/workers.ts
CHANGED
|
@@ -9,8 +9,8 @@ import { join } from "node:path";
|
|
|
9
9
|
import { argsOf, commandOf, readPrefs, withEnv, type Prefs } from "./agent-prefs.ts";
|
|
10
10
|
import { clip, reportBlocked, reportUnblock, validId } from "./report.ts";
|
|
11
11
|
import { read } from "./settings.ts";
|
|
12
|
-
import { accountEnv, accountForRun, agentFlags, agentUsable, detectDefaultAgent, MODEL_FLAGS, plainModel, promptArgs, readText, runAgent, YOLO_FLAGS } from "./state.ts";
|
|
13
|
-
import { branchOf, run as sh } from "./worktree.ts";
|
|
12
|
+
import { accountEnv, accountForRun, agentFlags, agentUsable, detectDefaultAgent, MODEL_FLAGS, plainModel, promptArgs, readText, runAgent, subagentEnv, YOLO_FLAGS } from "./state.ts";
|
|
13
|
+
import { branchFor, branchOf, run as sh } from "./worktree.ts";
|
|
14
14
|
|
|
15
15
|
export type Status = "planned" | "requested" | "running" | "blocked" | "succeeded" | "failed" | "unverified" | "conflict" | "merged" | "stopped";
|
|
16
16
|
export type Worker = {
|
|
@@ -42,7 +42,7 @@ function locked<T>(project: string, id: string, fn: () => T): T {
|
|
|
42
42
|
const lock = fileOf(project, id) + ".lock";
|
|
43
43
|
for (let i = 0; ; i++) {
|
|
44
44
|
try { mkdirSync(lock); break; } catch {
|
|
45
|
-
try { if (Date.now() - statSync(lock).mtimeMs > 10_000)
|
|
45
|
+
try { if (Date.now() - statSync(lock).mtimeMs > 10_000) { const aside = `${lock}.${process.pid}.${i}.stale`; renameSync(lock, aside); rmSync(aside, { recursive: true, force: true }); } } catch { /* gone */ }
|
|
46
46
|
if (i > 60) throw new Error("workers.json is locked: try again");
|
|
47
47
|
Bun.sleepSync(50);
|
|
48
48
|
}
|
|
@@ -200,6 +200,17 @@ export function launchOf(project: string, id: string, x: Worker, permissions: "o
|
|
|
200
200
|
return { ...l, title: `Worker ${x.id}${l.bypass ? " · bypass" : ""}`, cwd: x.worktree, env: { KAIZEN_RUN_ID: id, KAIZEN_WORKER: x.id } };
|
|
201
201
|
}
|
|
202
202
|
|
|
203
|
+
/** The model for this run's handoff agent: agent.handoff_model.<the run's tool>, project first. "": the run's own. */
|
|
204
|
+
export function handoffModel(project: string, id: string): string {
|
|
205
|
+
const cmd = runAgent(join(project, ".kaizen"), id)?.cmd ?? stateOf(project, id)?.agent;
|
|
206
|
+
if (typeof cmd !== "string" || !/^\w+$/.test(cmd)) return "";
|
|
207
|
+
for (const f of [join(project, ".kaizen", "config.yml"), join(homedir(), ".kaizen", "config.yml")]) {
|
|
208
|
+
const v = existsSync(f) ? read(readText(f), `agent.handoff_model.${cmd}`) : null;
|
|
209
|
+
if (v) return plainModel(v) ? v : "";
|
|
210
|
+
}
|
|
211
|
+
return "";
|
|
212
|
+
}
|
|
213
|
+
|
|
203
214
|
/** The run's agent as a command line with `prompt`. Shared with the handoff; the caller names the terminal. */
|
|
204
215
|
export function agentLine(project: string, id: string, prompt: string, permissions: "own" | "bypass", prefs: Prefs = readPrefs(), pick = ""): Omit<Launch, "title" | "cwd" | "env"> | string {
|
|
205
216
|
const own = runAgent(join(project, ".kaizen"), id), st = stateOf(project, id);
|
|
@@ -213,8 +224,10 @@ export function agentLine(project: string, id: string, prompt: string, permissio
|
|
|
213
224
|
const bypass = permissions === "bypass" && !!YOLO_FLAGS[agent.cmd];
|
|
214
225
|
const flags = [...agentFlags(project, agent.cmd, undefined, model), ...(bypass ? YOLO_FLAGS[agent.cmd]! : []), ...argsOf(agent.cmd, prefs)];
|
|
215
226
|
const line = withEnv([commandOf(agent.cmd, prefs), ...flags, ...promptArgs(agent.cmd, prompt)], agent.cmd, prefs);
|
|
227
|
+
// Windows has no env command: there only an account, as before, gets one.
|
|
228
|
+
const vars = [...(process.platform !== "win32" ? subagentEnv(project, agent.cmd) : []), ...accountEnv(acct)];
|
|
216
229
|
return {
|
|
217
|
-
argv:
|
|
230
|
+
argv: vars.length ? ["env", ...vars, ...line] : line, bypass, agent: agent.cmd,
|
|
218
231
|
model: picked ? (MODEL_FLAGS[agent.cmd] ? picked : undefined) : model ?? agentFlags(project, agent.cmd).join(" ").match(/\S+$/)?.[0],
|
|
219
232
|
modelNote: picked && !MODEL_FLAGS[agent.cmd] ? `${agent.name} takes no model flag: "${picked}" was ignored` : undefined,
|
|
220
233
|
trust: acct.dir ? join(acct.dir, ".claude.json") : undefined,
|
|
@@ -238,7 +251,7 @@ export function startWorker(project: string, id: string, wid: string, prefs?: Pr
|
|
|
238
251
|
const have = git(project, "rev-parse", "--verify", "--quiet", `refs/heads/${x.branch}`).ok;
|
|
239
252
|
// A dependent worker starts from the worker it follows, so it sees that code; any further `after` workers are merged in.
|
|
240
253
|
const dep = x.after.map((a) => w.workers.find((o) => o.id === a)!.branch);
|
|
241
|
-
const add = git(project, "worktree", "add", ...(have ? [x.worktree, x.branch] : ["--no-track", "-b", x.branch, x.worktree, dep[0] ??
|
|
254
|
+
const add = git(project, "worktree", "add", ...(have ? [x.worktree, x.branch] : ["--no-track", "-b", x.branch, x.worktree, dep[0] ?? branchFor(project, id)]));
|
|
242
255
|
if (!add.ok) return { ok: false, why: add.why };
|
|
243
256
|
if (!have) for (const b of dep.slice(1)) {
|
|
244
257
|
const m = git(x.worktree, "merge", "--no-edit", b);
|
|
@@ -326,12 +339,12 @@ export function merge(project: string, id: string): { ok: true; shas: string[];
|
|
|
326
339
|
if (not) return { ok: false, why: `${not.id} is ${not.status}, so nothing is merged: ${NEXT[not.status]?.replace("<wid>", not.id)}` };
|
|
327
340
|
const cwd = st.worktree as string;
|
|
328
341
|
if (!cwd || !existsSync(cwd)) return { ok: false, why: "the run has no worktree to merge into" };
|
|
329
|
-
if (git(cwd, "rev-parse", "--abbrev-ref", "HEAD").out !==
|
|
342
|
+
if (git(cwd, "rev-parse", "--abbrev-ref", "HEAD").out !== branchFor(project, id)) return { ok: false, why: `the run's worktree is not on ${branchFor(project, id)}: check it out there first` };
|
|
330
343
|
if (git(cwd, "status", "--porcelain").out) return { ok: false, why: "the run's worktree has uncommitted changes: commit them first, then merge" };
|
|
331
344
|
// A branch may change only what its worker owns. Commits it took from the workers it follows are theirs, not its own.
|
|
332
345
|
for (const x of w.workers) {
|
|
333
346
|
const skip = x.after.flatMap((a) => ["^" + w.workers.find((o) => o.id === a)!.branch]);
|
|
334
|
-
const out = git(cwd, "log", "--no-merges", "--name-only", "--format=", x.branch, "^" +
|
|
347
|
+
const out = git(cwd, "log", "--no-merges", "--name-only", "--format=", x.branch, "^" + branchFor(project, id), ...skip).out.split("\n").filter(Boolean);
|
|
335
348
|
const stray = [...new Set(out)].filter((p) => !x.owns.some((o) => p === o || p.startsWith(o + "/")));
|
|
336
349
|
if (stray.length) return { ok: false, why: `${x.id} changed paths it does not own (${stray.slice(0, 5).join(", ")}): nothing is merged. Move those changes out of its branch, or tell the user` };
|
|
337
350
|
}
|
package/cli/worktree.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// One branch and one git worktree per run, so agents building at the same time never
|
|
2
2
|
// share a working folder. Run notes stay in the project's .kaizen/runs/<id>/; only the
|
|
3
3
|
// code lives in the worktree. Every git call is an argv array, never a shell string.
|
|
4
|
-
import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, renameSync, realpathSync } from "node:fs";
|
|
4
|
+
import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync, renameSync, realpathSync } from "node:fs";
|
|
5
5
|
import { join, dirname, resolve, sep } from "node:path";
|
|
6
6
|
import { homedir } from "node:os";
|
|
7
7
|
import { branchesOf } from "./add-project.ts";
|
|
@@ -23,6 +23,34 @@ export const run: Run = (cmd, cwd, ms = 120_000) => {
|
|
|
23
23
|
const git = (cwd: string, ...a: string[]) => run(["git", ...a], cwd);
|
|
24
24
|
|
|
25
25
|
export const branchOf = (id: string) => `kaizen/${id}`;
|
|
26
|
+
// A branch name that is safe as a git argument and a refs/heads path: no leading dash, no "..", no "//", no spaces.
|
|
27
|
+
const SAFE_BRANCH = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,199}$/;
|
|
28
|
+
const safeBranch = (b: unknown): b is string => typeof b === "string" && SAFE_BRANCH.test(b) && !b.includes("..") && !b.includes("//") && !/[/.]$/.test(b) && !b.endsWith(".lock");
|
|
29
|
+
/** The branch a run really has: the one its state.json records (a run made by hand, on a feature branch), else kaizen/<id>.
|
|
30
|
+
* Never the base it lands on (the remote default, the feature base, HEAD): landing and cleanup delete this branch. */
|
|
31
|
+
export function branchFor(project: string, id: string): string {
|
|
32
|
+
try {
|
|
33
|
+
const b = JSON.parse(readFileSync(join(project, ".kaizen", "runs", id, "state.json"), "utf8")).branch;
|
|
34
|
+
if (safeBranch(b) && b !== "HEAD" && b !== localBase(project, id) && b !== baseOf(project)) return b;
|
|
35
|
+
} catch { /* no state: the default */ }
|
|
36
|
+
return branchOf(id);
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** Another run that still uses this run's branch or worktree (runs made by hand on one feature branch share both):
|
|
40
|
+
* neither is ours to remove while it does. */
|
|
41
|
+
function sharer(project: string, id: string, branch: string, dir: string): string | null {
|
|
42
|
+
const runs = join(project, ".kaizen", "runs");
|
|
43
|
+
let names: string[] = [];
|
|
44
|
+
try { names = readdirSync(runs); } catch { return null; }
|
|
45
|
+
for (const n of names) {
|
|
46
|
+
if (n === id) continue;
|
|
47
|
+
try {
|
|
48
|
+
const o = JSON.parse(readFileSync(join(runs, n, "state.json"), "utf8"));
|
|
49
|
+
if (typeof o.worktree === "string" && o.worktree && existsSync(o.worktree) && (o.worktree === dir || o.branch === branch)) return n;
|
|
50
|
+
} catch { /* not a run */ }
|
|
51
|
+
}
|
|
52
|
+
return null;
|
|
53
|
+
}
|
|
26
54
|
export const worktreeOf = (project: string, id: string) => join(project, ".kaizen", "wt", id);
|
|
27
55
|
|
|
28
56
|
const file = (project: string, id: string) => join(project, ".kaizen", "runs", id, "state.json");
|
|
@@ -37,7 +65,8 @@ function patchState(project: string, id: string, set: Record<string, unknown>) {
|
|
|
37
65
|
export function codeDir(project: string, id: string): string {
|
|
38
66
|
try {
|
|
39
67
|
const w = JSON.parse(readFileSync(file(project, id), "utf8")).worktree;
|
|
40
|
-
|
|
68
|
+
// Only a folder under <project>/.kaizen/wt/: a hand-written state.json must not aim land or cleanup at another checkout.
|
|
69
|
+
if (typeof w === "string" && existsSync(w) && resolve(w).startsWith(join(resolve(project), ".kaizen", "wt") + sep)) return w;
|
|
41
70
|
} catch { /* no state, no worktree */ }
|
|
42
71
|
return project;
|
|
43
72
|
}
|
|
@@ -64,9 +93,10 @@ const baseRef = (project: string, id: string) => localBase(project, id) ?? `orig
|
|
|
64
93
|
/**
|
|
65
94
|
* Makes the run's worktree and branch and records both. Off the remote default branch, or,
|
|
66
95
|
* when the project is on another branch, off that local branch, unpushed commits included,
|
|
67
|
-
* recorded as `base_branch`. `
|
|
96
|
+
* recorded as `base_branch`. `fromDefault` (a side run) always cuts from the remote default
|
|
97
|
+
* branch, whatever the project is on. `warn` names uncommitted changes, which a worktree never carries.
|
|
68
98
|
*/
|
|
69
|
-
export function startWorktree(project: string, id: string): { ok: true; path: string; branch: string; warn?: string } | { ok: false; why: string } {
|
|
99
|
+
export function startWorktree(project: string, id: string, fromDefault = false): { ok: true; path: string; branch: string; warn?: string } | { ok: false; why: string } {
|
|
70
100
|
if (!SLUG.test(id)) return { ok: false, why: `"${id}" is not a run id` };
|
|
71
101
|
if (!existsSync(file(project, id))) return { ok: false, why: "no such run" };
|
|
72
102
|
if (!git(project, "rev-parse", "--is-inside-work-tree").ok) return { ok: false, why: "not a git repository" };
|
|
@@ -75,7 +105,7 @@ export function startWorktree(project: string, id: string): { ok: true; path: st
|
|
|
75
105
|
if (!git(project, "remote").out) return { ok: false, why: "no git remote to branch from" };
|
|
76
106
|
const f = git(project, "fetch", "origin");
|
|
77
107
|
if (!f.ok) return { ok: false, why: `fetch failed: ${f.why}` };
|
|
78
|
-
const here = git(project, "symbolic-ref", "--short", "-q", "HEAD"), feature = here.ok && here.out && here.out !== baseOf(project) ? here.out : null;
|
|
108
|
+
const here = git(project, "symbolic-ref", "--short", "-q", "HEAD"), feature = !fromDefault && here.ok && here.out && here.out !== baseOf(project) ? here.out : null;
|
|
79
109
|
const base = feature ?? `origin/${baseOf(project)}`;
|
|
80
110
|
const exists = git(project, "rev-parse", "--verify", "--quiet", `refs/heads/${branch}`).ok;
|
|
81
111
|
const add = git(project, "worktree", "add", ...(exists ? [path, branch] : [path, "--no-track", "-b", branch, base]));
|
|
@@ -92,11 +122,17 @@ type Failed = Extract<Landed, { ok: false }>;
|
|
|
92
122
|
// The project's own config over the global one; the defaults are safe: nothing auto-resolves.
|
|
93
123
|
// Read here because settings.ts loads state.ts, which loads this file.
|
|
94
124
|
const readGit = (text: string, key: string) => {
|
|
95
|
-
const m = new RegExp(`^git:[^\\n]*\\n(?:(?:[ \\t]
|
|
125
|
+
const m = new RegExp(`^git:[^\\n]*\\n(?:(?:[ \\t][^\\n]*)?\\n)*?[ \\t]+${key}:[ \\t]*([^\\n]*)`, "m").exec(text.replace(/\r\n/g, "\n"));
|
|
96
126
|
return m ? m[1]!.split(" #")[0]!.trim().replace(/^["']|["']$/g, "") : null;
|
|
97
127
|
};
|
|
128
|
+
// A command run through `sh -c`: a project's config.yml that git tracks came with a clone, so it may not set one.
|
|
129
|
+
const COMMAND_KEYS = new Set(["land_check", "rebuild_on_land"]);
|
|
130
|
+
const tracked = (project: string, f: string) => {
|
|
131
|
+
try { return Bun.spawnSync(["git", "-C", project, "ls-files", "--error-unmatch", f], { stdout: "ignore", stderr: "ignore", windowsHide: true }).exitCode === 0; } catch { return false; }
|
|
132
|
+
};
|
|
98
133
|
const gitSetting = (project: string, key: string, fallback: string) => {
|
|
99
134
|
for (const f of [join(project, ".kaizen", "config.yml"), join(homedir(), ".kaizen", "config.yml")]) {
|
|
135
|
+
if (COMMAND_KEYS.has(key) && f.startsWith(project) && tracked(project, f)) continue;
|
|
100
136
|
try { const v = readGit(readFileSync(f, "utf8"), key); if (v !== null) return v; } catch { /* no such file */ }
|
|
101
137
|
}
|
|
102
138
|
return fallback;
|
|
@@ -208,7 +244,7 @@ export function landWorktree(project: string, id: string, sh: Run = run,
|
|
|
208
244
|
// gh only knows GitHub: any other remote lands by rebase and push.
|
|
209
245
|
hasGh = !!Bun.which("gh") && /github\.com/.test(git(project, "remote", "get-url", "origin").out)): Landed {
|
|
210
246
|
if (!SLUG.test(id)) return { ok: false, why: `"${id}" is not a run id` };
|
|
211
|
-
const dir = codeDir(project, id), branch =
|
|
247
|
+
const dir = codeDir(project, id), branch = branchFor(project, id);
|
|
212
248
|
if (dir === project) return { ok: false, why: "this run has no worktree" };
|
|
213
249
|
const clean = (d: string) => !sh(["git", "status", "--porcelain"], d).out;
|
|
214
250
|
if (!clean(dir)) return { ok: false, why: "the worktree has uncommitted changes; commit them first" };
|
|
@@ -227,9 +263,10 @@ export function landWorktree(project: string, id: string, sh: Run = run,
|
|
|
227
263
|
const m = sh(["git", "merge", "--no-edit", branch], project);
|
|
228
264
|
if (!m.ok) { sh(["git", "merge", "--abort"], project); return { ok: false, kind: "conflict", why: `merge into ${feature} failed: ${m.why}; worktree kept` }; }
|
|
229
265
|
}
|
|
266
|
+
if (sharer(project, id, branch, dir)) return { ok: true, how: "merge" }; // merged; another run still uses the worktree and branch
|
|
230
267
|
const rm = git(project, "worktree", "remove", "--force", dir);
|
|
231
268
|
if (!rm.ok) return { ok: false, why: `merged, but the worktree stays: ${rm.why}` };
|
|
232
|
-
git(project, "branch", "-D", branch);
|
|
269
|
+
git(project, "branch", "-D", "--", branch);
|
|
233
270
|
patchState(project, id, { worktree: null, branch: null });
|
|
234
271
|
return { ok: true, how: "merge" };
|
|
235
272
|
}
|
|
@@ -237,11 +274,12 @@ export function landWorktree(project: string, id: string, sh: Run = run,
|
|
|
237
274
|
const finish = (how: "pr" | "push", url?: string): Landed => {
|
|
238
275
|
git(project, "fetch", "origin");
|
|
239
276
|
if (!landed(dir, `origin/${base}`, branch)) return { ok: false, why: `${how === "pr" ? "the pull request" : "the push"} went through but ${branch} is not on ${base} yet; worktree kept` };
|
|
277
|
+
if (sharer(project, id, branch, dir)) return { ok: true, how, url }; // landed; another run still uses the worktree and branch
|
|
240
278
|
// The worktree is clean (checked above); --force is only for the untracked node_modules link.
|
|
241
279
|
const rm = git(project, "worktree", "remove", "--force", dir);
|
|
242
280
|
if (!rm.ok) return { ok: false, why: `landed, but the worktree stays: ${rm.why}` };
|
|
243
|
-
git(project, "branch", "-D", branch);
|
|
244
|
-
git(project, "push", "origin", "--delete", branch);
|
|
281
|
+
git(project, "branch", "-D", "--", branch);
|
|
282
|
+
git(project, "push", "origin", "--delete", "--", branch);
|
|
245
283
|
patchState(project, id, { worktree: null, branch: null });
|
|
246
284
|
return { ok: true, how, url };
|
|
247
285
|
};
|
|
@@ -314,7 +352,7 @@ export function branchState(project: string, id: string, changed: () => void = (
|
|
|
314
352
|
if (!SLUG.test(id)) return null;
|
|
315
353
|
const dir = codeDir(project, id);
|
|
316
354
|
if (dir === project) return null; // committed in the project's own checkout: no branch of its own
|
|
317
|
-
const branch =
|
|
355
|
+
const branch = branchFor(project, id), base = baseOfRun(project, id), ref = baseRef(project, id);
|
|
318
356
|
// A feature base may never have been pushed: it lands by local merge, with no pull request.
|
|
319
357
|
const gh = hasGh && !localBase(project, id);
|
|
320
358
|
const upstream = sh(["git", "rev-parse", "--abbrev-ref", `${branch}@{u}`], dir).ok;
|
|
@@ -339,7 +377,7 @@ export function branchState(project: string, id: string, changed: () => void = (
|
|
|
339
377
|
/** Pushes the branch, then opens its pull request against the base. */
|
|
340
378
|
export async function openPr(project: string, id: string, title: string, body: string, draft: boolean, sh: Run = run, ash: AsyncRun = runAsync, hasGh = onGithub(project)): Promise<{ ok: true; pr: Pr } | { ok: false; why: string }> {
|
|
341
379
|
if (!SLUG.test(id)) return { ok: false, why: `"${id}" is not a run id` };
|
|
342
|
-
const dir = codeDir(project, id), branch =
|
|
380
|
+
const dir = codeDir(project, id), branch = branchFor(project, id);
|
|
343
381
|
if (dir === project) return { ok: false, why: "This run has no branch of its own." };
|
|
344
382
|
if (localBase(project, id)) return { ok: false, why: "This run lands by a local merge into its branch, with no pull request." };
|
|
345
383
|
if (!hasGh) return { ok: false, why: "Pull requests need the GitHub CLI (gh) and a GitHub remote." };
|
|
@@ -358,7 +396,7 @@ export async function openPr(project: string, id: string, title: string, body: s
|
|
|
358
396
|
/** Merges the run's pull request by rebase, as `kaizen land` does. The worktree stays. */
|
|
359
397
|
export async function mergePr(project: string, id: string, sh: Run = run, ash: AsyncRun = runAsync, hasGh = onGithub(project)): Promise<{ ok: true } | { ok: false; why: string }> {
|
|
360
398
|
if (!SLUG.test(id)) return { ok: false, why: `"${id}" is not a run id` };
|
|
361
|
-
const dir = codeDir(project, id), branch =
|
|
399
|
+
const dir = codeDir(project, id), branch = branchFor(project, id);
|
|
362
400
|
if (dir === project) return { ok: false, why: "This run has no branch of its own." };
|
|
363
401
|
if (localBase(project, id)) return { ok: false, why: "This run lands by a local merge: run kaizen worktree land." };
|
|
364
402
|
if (!hasGh) return { ok: false, why: "Merging needs the GitHub CLI (gh) and a GitHub remote." };
|
|
@@ -375,8 +413,10 @@ export async function mergePr(project: string, id: string, sh: Run = run, ash: A
|
|
|
375
413
|
*/
|
|
376
414
|
export async function removeWorktree(project: string, id: string, sh: Run = run, ash: AsyncRun = runAsync): Promise<{ ok: true } | { ok: false; why: string }> {
|
|
377
415
|
if (!SLUG.test(id)) return { ok: false, why: `"${id}" is not a run id` };
|
|
378
|
-
const dir = codeDir(project, id), branch =
|
|
416
|
+
const dir = codeDir(project, id), branch = branchFor(project, id);
|
|
379
417
|
if (dir === project) return { ok: false, why: "This run has no worktree." };
|
|
418
|
+
const other = sharer(project, id, branch, dir);
|
|
419
|
+
if (other) return { ok: false, why: `The run ${other} still uses this worktree and branch. Remove them from the last run that uses them.` };
|
|
380
420
|
if (sh(["git", "status", "--porcelain"], dir).out) return { ok: false, why: "The worktree has uncommitted changes. Commit or discard them first." };
|
|
381
421
|
const feature = localBase(project, id), base = feature ?? baseOf(project), ref = baseRef(project, id);
|
|
382
422
|
if (!feature) {
|
|
@@ -390,7 +430,7 @@ export async function removeWorktree(project: string, id: string, sh: Run = run,
|
|
|
390
430
|
if (!rm.ok) return { ok: false, why: rm.why };
|
|
391
431
|
// Every commit is on the base by patch, so -D loses nothing a rebase-merge rewrote.
|
|
392
432
|
sh(["git", "branch", "-D", "--", branch], project);
|
|
393
|
-
if (!feature) await ash(["git", "push", "origin", "--delete", branch], project); // best effort: GitHub may have deleted it
|
|
433
|
+
if (!feature) await ash(["git", "push", "origin", "--delete", "--", branch], project); // best effort: GitHub may have deleted it
|
|
394
434
|
prs.delete(prKey(project, id));
|
|
395
435
|
patchState(project, id, { worktree: null, branch: null });
|
|
396
436
|
clearLand(project, id);
|
package/package.json
CHANGED
package/skills/kaizen/SKILL.md
CHANGED
|
@@ -117,7 +117,7 @@ This is a judgement, not a threshold to enforce: fifty lines that change how mon
|
|
|
117
117
|
rounded are not a small change. Say which path you took (short or full) and why, in one line, when the
|
|
118
118
|
run starts.
|
|
119
119
|
|
|
120
|
-
**Follow-ups are runs too.** Both runners record the same artifacts: `01-plan.md`, `03-impl.md`, `04-review.md`, and a final `state.json` — `lite` and `full` differ only in who executes the stages. A message the user sends later in the same session is judged by what it asks: a question, explanation or chat is answered, no run; a request to change or produce something is building, so it goes through the flow. While the previous run has not reached `done` (including awaiting its final approval),
|
|
120
|
+
**Follow-ups are runs too.** Both runners record the same artifacts: `01-plan.md`, `03-impl.md`, `04-review.md`, and a final `state.json` — `lite` and `full` differ only in who executes the stages. A message the user sends later in the same session is judged by what it asks: a question, explanation or chat is answered, no run; a request to change or produce something is building, so it goes through the flow. While the previous run has not reached `done` (including awaiting its final approval), a change to that run's own work is a revise of it, recorded in `02-approval.md` ("make the new panel narrower" while that panel is being built). A request for something else while a run is in flight (a bug in another area found mid-feature, an unrelated fix) asks first, AskUserQuestion: *Side run: new worktree off the default branch, built by a second agent* (recommended), *Side run: new worktree off the default branch, built in this session* (in the side run's own worktree, never the other run's folder), *Revise the current run*, *Answer without a run*; create nothing under `runs/` until a side run is picked. **A side run** is a new run, started like any other with its own fresh `state.json`: never copy another run's `state.json`, and never carry over its `worktree`, `branch`, `workspace`, `session`, `base_branch` or `base_sha`. Its `00-request.md` ends with `Follow-up of: <the run in flight>`. Plan it and take its plan approval as usual, then run `kaizen worktree start <id> --default` from the project folder or any worktree: it cuts `kaizen/<id>` from the remote default branch and never places the run in the folder you are in. For the second agent, run `kaizen handoff start <id>` as `spec-build.md` says. This works under `lite` and `full` alike. Either way, go back to the run in flight; the side run never changes it. After `done` or `abandoned`, ask the user before opening a new run — AskUserQuestion with *open a follow-up run*, *answer without a run*, *cancel* — and create nothing under `runs/` until they pick the first. An explicit `/kaizen <request>` is that answer already. The new run's `00-request.md` is the user's words verbatim, then a line `Follow-up of: <previous run id>`; where those words only answer a question ("Plan 2b next"), put one line naming the work first — the board titles the card from it. Never reopen a finished run. When unsure whether a message asks for a change, ask once.
|
|
121
121
|
|
|
122
122
|
## Modes
|
|
123
123
|
|
|
@@ -251,7 +251,9 @@ final report, so nobody reads a same-session review as an independent one.
|
|
|
251
251
|
session at a time) runs as `lite` whatever the setting, following
|
|
252
252
|
[`adapters.md`](adapters.md); do not fake subagents.
|
|
253
253
|
|
|
254
|
-
- `runner: lite` — do not call the Agent tool, except for the review as below.
|
|
254
|
+
- `runner: lite` — do not call the Agent tool, except for the review as below. Handing a
|
|
255
|
+
worktree run to a second agent with `kaizen handoff start` is not the Agent tool and is
|
|
256
|
+
allowed under `lite` too (`spec-build.md`). Otherwise you run
|
|
255
257
|
plan, build and review yourself, as *Who runs the stages* says; the stage table below
|
|
256
258
|
still applies, and you are the agent for every row.
|
|
257
259
|
Read `spec-build.md` before building and `spec-main.md` before moving the run to
|
|
@@ -283,12 +285,14 @@ the choice at the plan approval. Building inline does not make the review less
|
|
|
283
285
|
independent: the reviewer is a separate agent in every case, and never sees the
|
|
284
286
|
conversation the work happened in.
|
|
285
287
|
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
288
|
+
Each stage subagent's model comes from `subagents.<stage>` (`planner`, `builder`,
|
|
289
|
+
`reviewer`), else `subagents.model`; the builder's value covers the fix rounds and the
|
|
290
|
+
reviewer's the rechecks. This holds for every stage dispatched this way, a lite run's
|
|
291
|
+
reviewer under `review.executor: subagent` included. Before each dispatch run
|
|
292
|
+
`kaizen model <stage>` and pass what it prints as `model` on the Agent call; `inherit`
|
|
293
|
+
means pass none. `subagents.effort` has no call-time knob: a session kaizen launches
|
|
294
|
+
already carries it, and the stage's model, in its environment. Never write `model:` or
|
|
295
|
+
`effort:` into an agent definition file: those files are shared by every project.
|
|
292
296
|
|
|
293
297
|
After a subagent returns, update `state.json` yourself in the main thread, with `kaizen state` from 1.69.0, by hand before that (`spec.md`, Stage 0). Subagents
|
|
294
298
|
report; the main thread owns the state machine.
|
|
@@ -169,8 +169,14 @@ subagents:
|
|
|
169
169
|
# opus | sonnet | haiku - pin it. A cheaper model for the builder is the usual
|
|
170
170
|
# reason to touch this; the reviewer on a cheaper model finds less.
|
|
171
171
|
model: inherit
|
|
172
|
+
# One stage on its own model, ahead of `model` above: default | opus | sonnet | haiku.
|
|
173
|
+
# The builder also runs the fix rounds, the reviewer the rechecks.
|
|
174
|
+
planner: default
|
|
175
|
+
builder: default
|
|
176
|
+
reviewer: default
|
|
172
177
|
# Reasoning effort for the stage subagents: inherit | low | medium | high.
|
|
173
|
-
#
|
|
178
|
+
# A Claude Code session kaizen launches carries model and effort as the defaults its
|
|
179
|
+
# subagents start from (CLAUDE_CODE_SUBAGENT_MODEL, CLAUDE_CODE_SUBAGENT_EFFORT).
|
|
174
180
|
effort: inherit
|
|
175
181
|
|
|
176
182
|
agent:
|
|
@@ -207,8 +213,18 @@ agent:
|
|
|
207
213
|
# (while kaizen is open). Linux and macOS; agents in an outside terminal don't count.
|
|
208
214
|
keep_awake: off
|
|
209
215
|
# The model each tool launches with, the tool's own name. Empty: its default.
|
|
210
|
-
# Claude Code's stage subagents use subagents.model
|
|
216
|
+
# Claude Code's stage subagents use subagents.model, and inherit this when it is inherit.
|
|
211
217
|
model:
|
|
218
|
+
claude: ""
|
|
219
|
+
agy: ""
|
|
220
|
+
codex: ""
|
|
221
|
+
gemini: ""
|
|
222
|
+
opencode: ""
|
|
223
|
+
# The model of the second agent a worktree run hands its build, review and fix loop to
|
|
224
|
+
# (`kaizen handoff start`), per tool, in the tool's own spelling. Empty: the run's own
|
|
225
|
+
# model. Claude's handoff agent still runs its stage subagents on subagents.*.
|
|
226
|
+
handoff_model:
|
|
227
|
+
claude: ""
|
|
212
228
|
agy: ""
|
|
213
229
|
codex: ""
|
|
214
230
|
gemini: ""
|
|
@@ -30,8 +30,10 @@ nearest first, so a change lands globally unless this project keeps its own conf
|
|
|
30
30
|
| `git.rebuild_on_land` | text | Command that remakes generated files after they were resolved |
|
|
31
31
|
| `git.land_check` | `auto`, `off`, or a command | Runs after a rebase that pulled commits; a failure stops the land |
|
|
32
32
|
| `ui.mouse` | `false`, `true` | Click to select, click again to act; while on, the terminal cannot select text |
|
|
33
|
-
| `agent.model.<tool>` | the tool's own model name, or empty | Launch model
|
|
33
|
+
| `agent.model.<tool>` | the tool's own model name, or empty | Launch model per tool. agy, codex, gemini, opencode run every stage on it; for claude it is the main session, which stage subagents on `inherit` follow |
|
|
34
|
+
| `agent.handoff_model.<tool>` | the tool's own model name, or empty | Model of the second agent a worktree run hands build, review and the fix loop to; empty is the run's own model |
|
|
34
35
|
| `subagents.model` | `inherit`, `opus`, `sonnet`, `haiku` | Model the stage subagents run on (Claude Code only) |
|
|
36
|
+
| `subagents.planner`, `subagents.builder`, `subagents.reviewer` | `default`, `opus`, `sonnet`, `haiku` | One stage on its own model, ahead of `subagents.model`; the builder also runs the fix rounds, the reviewer the rechecks (Claude Code only) |
|
|
35
37
|
| `subagents.effort` | `inherit`, `low`, `medium`, `high` | Reasoning effort for the stage subagents (Claude Code only) |
|
|
36
38
|
| `sources.every` | `off`, `1h`, `6h`, `24h` | How often the web board checks request sources for new requests, into the icebox, while it runs |
|
|
37
39
|
| `sources.agent` | `ask`, `chatgpt`, `agent` | Who picks the posts that fit from social sources when Gather is pressed: the ChatGPT plan signed in from the Icebox, or your agent on `/kaizen gather` |
|
|
@@ -55,7 +55,8 @@ code in the same folder. If `kaizen worktree start` fails, say why and stop; do
|
|
|
55
55
|
back to the project folder unasked. A run whose `state.json` has no `worktree` builds in
|
|
56
56
|
place, exactly as before.
|
|
57
57
|
|
|
58
|
-
**Hand the build to a second agent, when the run gets a worktree.**
|
|
58
|
+
**Hand the build to a second agent, when the run gets a worktree.** This applies under every
|
|
59
|
+
runner, `lite` included: the second agent is a board terminal, not a subagent. The agent the user is
|
|
59
60
|
talking to stays with them. Before `kaizen worktree start`, it writes into `02-approval.md`
|
|
60
61
|
every decision made in chat that the plan lacks: the second agent never sees the chat. After
|
|
61
62
|
it, it runs `kaizen handoff start <id>`. Exit 0: say the worktree agent is building, and end
|
|
@@ -66,7 +67,17 @@ same rules (it is the coordinator if the plan has approved workers), and ends wi
|
|
|
66
67
|
`kaizen handoff done` or `kaizen handoff blocked "<reason>"`. It never runs `kaizen done`
|
|
67
68
|
or `kaizen worktree land`. It takes no bypass from Orchestration. `runs/<id>/handoff.json`
|
|
68
69
|
is written only by these commands and the board. A worktree cut while the project is on a
|
|
69
|
-
branch other than the default is cut from that local branch and records `base_branch
|
|
70
|
+
branch other than the default is cut from that local branch and records `base_branch`,
|
|
71
|
+
except with `--default`.
|
|
72
|
+
|
|
73
|
+
**A side run** (opened while another run is in flight, `SKILL.md` *Follow-ups are runs
|
|
74
|
+
too*) starts its worktree with `kaizen worktree start <id> --default`, so its branch comes
|
|
75
|
+
off the remote default branch and it never builds in the other run's folder. When the user
|
|
76
|
+
picked a second agent: exit 0 from `kaizen handoff start` means say the worktree agent is
|
|
77
|
+
building the side run, then go back to the run in flight instead of ending the turn; its
|
|
78
|
+
files, worktree and stage are untouched. Exit 3: ask the user whether to build the side run
|
|
79
|
+
here, in its own worktree, or leave it at its approved plan; never build it in the other
|
|
80
|
+
run's worktree. A side run without a remote to branch from stops and says so.
|
|
70
81
|
|
|
71
82
|
**Workers, only when the run has them.** When `01-plan.md` has a `## Workers` section and
|
|
72
83
|
`02-approval.md` says `workers: approved`, the build agent is the coordinator. Run
|
|
@@ -96,6 +96,8 @@ Woken by the line `kaizen run <id>: the worktree agent ended (...)`, or asked ab
|
|
|
96
96
|
read `state.json`, `handoff.json`, `03-impl.md` and `04-review.md`, whatever the line says:
|
|
97
97
|
it is a pointer, not a result. `done`: report what changed, the checks and open findings,
|
|
98
98
|
then take the final approval and land as usual; in `auto` carry on without stopping.
|
|
99
|
+
A side run's line can arrive while this agent is busy with another run: report the side run
|
|
100
|
+
and take its final approval without changing the other run's files or stage.
|
|
99
101
|
`blocked`, `failed` or `quiet`: say why and what is left, and keep the worktree. `quiet` means the second agent went silent and may still report; `kaizen handoff start <id>` opens a new one on the same worktree. A run with
|
|
100
102
|
`base_branch` lands by a local merge into that branch, with no push; if the project folder
|
|
101
103
|
is on another branch or the merge conflicts, `kaizen worktree land` says so and keeps the
|
|
@@ -28,6 +28,7 @@ anything.
|
|
|
28
28
|
| `/kaizen review [target]` | Review-only: audit existing code, no plan, no implementation |
|
|
29
29
|
| `/kaizen status` | List every run grouped waiting-on-you / in flight / done / abandoned, plus open backlog count |
|
|
30
30
|
| `kaizen done <id> [--user-approved]` | Finish a run; refused while the review gate waits on the user, `--user-approved` after a clear yes in chat |
|
|
31
|
+
| `kaizen model [planner\|builder\|reviewer]` | The model to pass on that stage subagent's Agent call, from `subagents.<stage>` then `subagents.model`; `inherit` means pass none |
|
|
31
32
|
| `kaizen state <id> key=value ...` | (1.69.0+) Set a run's `stage`, `awaiting` or `iteration` in `state.json`; refuses words no board knows (`done` goes through `kaizen done`) |
|
|
32
33
|
| `kaizen stats [<id>] [--json]` | (1.69.0+) Fix-round and CANNOT VERIFY rates, stage times, tokens for one run |
|
|
33
34
|
| `kaizen related <path> ...` | (1.69.0+) Earlier runs that changed these files |
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: kaizen-game
|
|
3
|
+
description: Design, build, verify and share any browser game (web track) — arcade, puzzle, runner, platformer, board or card game, 3D toy world, idle or story game, campaign or learning game — as a phone-first page with Three.js or plain Canvas/DOM, levels or rounds as separate modules, real-input Playwright play-throughs, frame-timing checks, and a public review link. Has an extra track for live event and learning games (content where the answer is an action in the game, rankings, a spectator view for Zoom). Use when the user wants to make a web game, a game design document (GDD), a playable game prototype, a game for an event, training or campaign, or wants an existing browser game fixed, smoothed or extended. Not for native, console or Unity/Godot games.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Kaizen game (web)
|
|
7
|
+
|
|
8
|
+
Any browser game, from brief to a link people can play: an arcade or puzzle game, a runner, a 3D toy world, a campaign game, a learning game.
|
|
9
|
+
The core flow (brief, concepts, GDD, build, verify, share) is the same for all of them.
|
|
10
|
+
|
|
11
|
+
**Tracks.** Pick one in the brief, and say which in the GDD:
|
|
12
|
+
- **Game** (default): any web game. Skip the content step and the event parts.
|
|
13
|
+
- **Event / learning**: a game with real-world content (training, compliance, onboarding, a campaign quiz) and often a live event with rankings and a shared screen.
|
|
14
|
+
This adds the "not a quiz in a skin" rule, the case model, `content.md`, and the run-of-show and spectator parts.
|
|
15
|
+
|
|
16
|
+
The lessons here come from a real event / learning project. It was a one-hour live compliance competition: 43 teams on phones, 12 playable rounds over two 3D islands, played in the browser, with Zoom used only by moderators.
|
|
17
|
+
It reached client review as a prototype. Steps marked **unproven** were planned there but not yet built. Say so when you reach them.
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
docs/
|
|
21
|
+
GDD.md GDD.pdf the design, approved before games are built
|
|
22
|
+
CONTENT-REVIEW.md event / learning track: every case with answer, reason, source, for the client's expert
|
|
23
|
+
.preview/ what the server shows
|
|
24
|
+
index.html landing: play link, downloads, "what's new" per version
|
|
25
|
+
game.html the game: one page, Three.js from an importmap, no build step
|
|
26
|
+
shared/data.js levels, tuning, content (one global, e.g. window.GDATA)
|
|
27
|
+
rounds/<key>.js one ES module per level or round, loaded with import() when it is entered
|
|
28
|
+
assets/ Kenney CC0 models and sounds actually used, with License.txt and CREDITS.md
|
|
29
|
+
v1/ v2/ … copies of game.html before each big pass
|
|
30
|
+
tools/serve.json which paths the public server may serve
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
`S=<this skill>/scripts`. Run scripts from the project folder.
|
|
34
|
+
|
|
35
|
+
## 0. Setup, once per machine
|
|
36
|
+
`$S/check.sh` lists what is missing (node, Playwright with Chromium, optional pandoc for the GDD PDF). `$S/setup.sh`
|
|
37
|
+
installs Playwright 1.62.1 and Chromium into `~/.kaizen/kaizen-game` (about 150 MB; tell the user first). If kaizen-book
|
|
38
|
+
already installed Playwright in `~/.kaizen/kaizen-book`, the scripts use that one.
|
|
39
|
+
|
|
40
|
+
## 1. Brief, then concepts
|
|
41
|
+
Read [`references/design.md`](references/design.md). Ask what kind of game it is, who plays, on what device, and how long a session lasts.
|
|
42
|
+
For the event / learning track, also ask **who the client is and their sector, before writing any content**. On the real project, content was first written for
|
|
43
|
+
the wrong sector and every case had to be rewritten.
|
|
44
|
+
When the direction is still open, run the `kaizen-concept` skill: truly different concepts, each with its signature
|
|
45
|
+
round playable to the result, on one review page. Build nothing big until one concept is picked.
|
|
46
|
+
|
|
47
|
+
## 2. GDD, approved
|
|
48
|
+
Write `docs/GDD.md` from the skeleton in `design.md`. Every game gets a core loop, controls on phone and laptop, a fail state and win state, tuning knobs, and a difficulty curve.
|
|
49
|
+
In the event / learning track, the rule that decides most of the design is that **the game is not a quiz in a skin**.
|
|
50
|
+
The question is a situation inside the game, and the answer is an action (dodge, stop, pick up, choose a path).
|
|
51
|
+
`node $S/gdd-pdf.mjs docs/GDD.md` builds `docs/GDD.pdf` for the client (needs pandoc).
|
|
52
|
+
Inside a kaizen run, the GDD approval is the plan approval.
|
|
53
|
+
|
|
54
|
+
## 3. Build
|
|
55
|
+
Read [`references/build.md`](references/build.md): page skeleton, `?screen=` jumps, the round shell, the module contract,
|
|
56
|
+
and the Three.js lessons (camera, disposal, touch, fallbacks), each of which cost a redo.
|
|
57
|
+
- Order that worked: playable flow first, then a UI pass (Apple HIG), then a richness pass (models, sound, light), then the real levels or rounds one by one.
|
|
58
|
+
- 2D games use the same skeleton with Canvas or DOM in place of Three.js. The lessons on screens, modules, fallbacks and verification still apply.
|
|
59
|
+
- Copy `game.html` to `v<N>/` before every big pass.
|
|
60
|
+
- Several rounds can be built at once by sub-agents, **one module file per agent**, with the contract in the reference module's header.
|
|
61
|
+
Write each agent a brief: files to read, a "keep" list of recent behaviour it must not undo, the verification, and the report format.
|
|
62
|
+
|
|
63
|
+
## 4. Content (event / learning track)
|
|
64
|
+
Read [`references/content.md`](references/content.md). Cases come from the client's real published rules, read in full.
|
|
65
|
+
Never invent an article number. Mark every case as a sample and list it in `docs/CONTENT-REVIEW.md`, with a column for what still needs the client's confirmation.
|
|
66
|
+
|
|
67
|
+
## 5. Verify
|
|
68
|
+
Read [`references/verify.md`](references/verify.md). The minimum before you say it works:
|
|
69
|
+
```
|
|
70
|
+
node $S/smoke.mjs http://127.0.0.1:4321/game.html --screens login,hub,result # 390×844 touch + 1440×900, errors, overflow, shots
|
|
71
|
+
node $S/frames.mjs http://127.0.0.1:4321/game.html?screen=hub --click 700,600 --gpu # frame gaps around one interaction
|
|
72
|
+
```
|
|
73
|
+
Then play every round **by real input** (taps, swipes, keys) to the result, once with mistakes, and look at every screenshot yourself.
|
|
74
|
+
"Smooth" is a measurement on the real GPU, not a guess. Swiftshader frame times mean nothing.
|
|
75
|
+
|
|
76
|
+
## 6. Share
|
|
77
|
+
Read [`references/ship.md`](references/ship.md). `PUBLIC=1 node $S/serve.mjs .preview 8060` serves only what
|
|
78
|
+
`tools/serve.json` allows. Expose it through the `deploy-tunnel` skill or any static host. Going public is outward-facing, so confirm with the user first.
|
|
79
|
+
Each version gets 3–5 "what's new" lines in the user's language on the landing page.
|
|
80
|
+
|
|
81
|
+
## Unproven (plan it, don't claim it)
|
|
82
|
+
Server-authoritative realtime or multiplayer play (WebSocket, a server clock, answer keys on the server), a host or moderator console,
|
|
83
|
+
saves that survive a refresh, a load test with simulated clients, tests on real cheap phones, and app-store wrapping. The GDD template
|
|
84
|
+
has sections for them. Until they are built, the prototype simulates other players, and the landing page says so.
|
|
85
|
+
|
|
86
|
+
## Improve this skill after each game
|
|
87
|
+
This skill grows from real projects. When a game reaches review, ask the user whether to fold its lessons back in, and add only what was proven in that project:
|
|
88
|
+
- a mistake that cost a redo goes to the "lessons" list of the matching reference, as one line with the measured evidence (`build.md`, `verify.md`, `content.md`);
|
|
89
|
+
- a check that caught a real bug goes into `verify.md` or a script;
|
|
90
|
+
- a step marked **unproven** that the project built and tested loses its mark, and its how-to goes into `ship.md` or `build.md`;
|
|
91
|
+
- a new genre that needed different rules gets its own short section in `design.md`.
|
|
92
|
+
Keep it generic: no client names, client content or project paths, because the skill is published.
|
|
93
|
+
|
|
94
|
+
## Kaizen
|
|
95
|
+
In a kaizen run: the brief and GDD approvals are the plan approval, each game or pass is a build, and the review plays
|
|
96
|
+
the game against the GDD using `verify.md`. Screenshots go in the run's `attachments/` for the Preview gate.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
@page { size: A4; margin: 18mm 16mm; }
|
|
2
|
+
body { font: 10.5pt/1.5 Inter, -apple-system, "Segoe UI", sans-serif; color: #1d1d1f; max-width: none; }
|
|
3
|
+
h1 { font-size: 22pt; letter-spacing: -0.02em; margin: 0 0 4pt; }
|
|
4
|
+
h2 { font-size: 14pt; margin: 18pt 0 6pt; padding-top: 8pt; border-top: 1px solid #e5e5ea; break-after: avoid; }
|
|
5
|
+
h3 { font-size: 11pt; } p, li { orphans: 3; widows: 3; }
|
|
6
|
+
header#title-block-header { display: none; }
|
|
7
|
+
table { border-collapse: collapse; width: 100%; font-size: 9pt; margin: 6pt 0 10pt; break-inside: auto; }
|
|
8
|
+
th, td { border-bottom: 1px solid #e5e5ea; padding: 4pt 6pt; text-align: left; vertical-align: top; }
|
|
9
|
+
th { background: #f5f5f7; font-weight: 600; } tr { break-inside: avoid; }
|
|
10
|
+
code { font-size: 8.5pt; background: #f5f5f7; padding: 0 3pt; border-radius: 3pt; }
|
|
11
|
+
pre { background: #f5f5f7; padding: 8pt; border-radius: 6pt; font-size: 8.5pt; white-space: pre-wrap; }
|
|
12
|
+
hr { border: 0; }
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# Build: page, rounds, Three.js lessons
|
|
2
|
+
|
|
3
|
+
## Stack for the prototype
|
|
4
|
+
- One `game.html`, no build step. Three.js from an importmap with an exact version, add-ons from the same version:
|
|
5
|
+
```html
|
|
6
|
+
<script type="importmap">{"imports":{"three":"https://cdn.jsdelivr.net/npm/three@0.170.0/build/three.module.js",
|
|
7
|
+
"three/addons/":"https://cdn.jsdelivr.net/npm/three@0.170.0/examples/jsm/"}}</script>
|
|
8
|
+
```
|
|
9
|
+
GLTFLoader, SkeletonUtils (to clone animated characters) and OrbitControls come from `three/addons/`.
|
|
10
|
+
- `shared/data.js` is a classic script setting one global (teams, rounds, cases), so concepts, game and tools all read the same data.
|
|
11
|
+
- Assets are Kenney CC0 packs (mini characters with animations, city, roads, car, nature, furniture kits, interface, impact and jingle sounds).
|
|
12
|
+
GLBs reference `Textures/colormap.png` next to them, so keep each pack's folder layout. Copy in only what you use, plus `License.txt`, and list the packs in `assets/CREDITS.md`.
|
|
13
|
+
Convert `.ogg` to `.m4a` (`ffmpeg -i x.ogg -c:a aac -b:a 96k x.m4a`) and pick by `audio.canPlayType`, because older iOS Safari cannot play Ogg.
|
|
14
|
+
- Music is a short procedural WebAudio loop that stays off until the first tap. One mute toggle controls everything.
|
|
15
|
+
- Targets: first load under 3 MB on 4G, each round under 1 MB extra, 30+ fps on a mid-range Android phone.
|
|
16
|
+
|
|
17
|
+
## Page skeleton
|
|
18
|
+
- **Screens.** One `go(name)` switches screens (login, character, lobby, hub, game, result, review, leaderboard, final, podium).
|
|
19
|
+
`?screen=<name>` jumps straight to any screen with sample state, so screenshots and agents need no click path. A direct jump into a game skips the intro and starts at once.
|
|
20
|
+
- **Spectator view.** `?view=spectator` (plus `&mode=final`) is a 1280×720 screen for the video call: large type (names 28 px or more, key numbers 48 px or more), flat colours (gradients turn to mush in compression), a room filter, and live top 10 bars.
|
|
21
|
+
- **Test hook.** `window.__game = { go, get view(), get S(), get gpu() }`, where `gpu` = `renderer.info.memory` plus counts. Scripts read state from it and never poke globals.
|
|
22
|
+
- **Honest labels.** Show a small "PROTOTYPE, simulated data" pill and a "sample question" note on content.
|
|
23
|
+
- **Fallbacks.** If WebGL is missing, each round has a 2D version. If GLBs fail to load (for example over `file://`), use primitive shapes. In both cases, log `console.warn` and never throw.
|
|
24
|
+
- **Accessibility.** Contrast at least 4.5:1, touch targets at least 44 px, a visible focus ring, labels on icon buttons, no colour-only signals.
|
|
25
|
+
Under `prefers-reduced-motion`, tweens jump to their end state. Every round must also be playable with laptop keys.
|
|
26
|
+
|
|
27
|
+
## Round shell and module contract
|
|
28
|
+
The page owns the clock, scoring and result. A round module only plays. Keep the contract as a comment at the top of the reference module, because every agent reads it there.
|
|
29
|
+
```
|
|
30
|
+
rounds/<key>.js
|
|
31
|
+
export const READY = true false = placeholder: the hub shows a "coming soon" sheet
|
|
32
|
+
export const ASSETS = [...] GLB paths preloaded before start()
|
|
33
|
+
export const CASES = [...] { id, prompt, action, reason, source } in play order (the review screen lists them)
|
|
34
|
+
export default function start(ctx)
|
|
35
|
+
|
|
36
|
+
ctx (everything a module may touch; it never reads page globals)
|
|
37
|
+
n, meta, root, stage, gl, THREE, data, S, RM (reduced motion)
|
|
38
|
+
sh: st { solved, wrong, pen, elapsed, running, ended }, total,
|
|
39
|
+
good(text, caseId) bad(text, spoken, caseId) (+penalty, case stays open)
|
|
40
|
+
miss(text, spoken, caseId) (+penalty, case closed) penalty(sec, text) end()
|
|
41
|
+
intro(steps, onStart) mount(view) makeCharacter(i) prop(path, opts) instanced(path, items)
|
|
42
|
+
lights(scene, …) tween(dur, fn, delay, done) sfx(name) say(text) buzz(ms)
|
|
43
|
+
later(fn, ms) every(fn, ms) onKey(fn) on(el, ev, fn) onSwipe(el, fn) (all removed on screen change)
|
|
44
|
+
```
|
|
45
|
+
- The shell ends the round when `solved === total`, or at the time limit including penalties. It stores the first result only, plus the solved and missed case ids for the review screen.
|
|
46
|
+
- `view = { scene, camera, resize(w, h), update(dt), onTap?, controls?(orbit), onMount?, onUnmount? }`.
|
|
47
|
+
- A module loads with `import()` when its building is entered. A missing or broken module shows the placeholder sheet instead of a blank screen.
|
|
48
|
+
- Once the shell and the reference module work, each further round is one file, so agents can build several at once.
|
|
49
|
+
|
|
50
|
+
## Three.js lessons (each one cost a redo)
|
|
51
|
+
- **One renderer, one canvas** for all screens. `mount(view)` and `unmount()` swap the scene and camera.
|
|
52
|
+
- **Release GPU memory on unmount.** Patch `EventDispatcher.prototype.addEventListener` so that every object registering a `'dispose'` listener goes into a `GPU` set.
|
|
53
|
+
That set is exactly what three.js uploaded. On unmount, dispose everything in it except the shared model, material and geometry caches.
|
|
54
|
+
Measured: textures 37 → 29 after five games in a row, against 137 → 445 without it. Also remove the DOM nodes the round created.
|
|
55
|
+
- **OrbitControls clamps zoom and angles every frame.** `minZoom`/`maxZoom` must cover every scripted camera move (intro, dive into a building). Otherwise the tween stalls halfway and looks like a stutter.
|
|
56
|
+
- **One camera move at a time.** Give each move a job id and ignore stale ones: `const id = ++camJob; tween(d, p => { if (id === camJob) fn(p); })`. Two tweens writing zoom at once jitter.
|
|
57
|
+
- **Never ease towards a stale target.** When flying to a building on a spinning island, ease the spin out first and aim at the building's live world position every frame.
|
|
58
|
+
- **`OrbitControls.dispose()` leaves an inline `touch-action: auto`** on the shared canvas. Clear it, or the next view loses its swipes to page scrolling.
|
|
59
|
+
- **Keep the old interactions when adding a new one.** Using drag to pan between islands silently removed drag-to-rotate, and the user noticed at once.
|
|
60
|
+
Before changing input handling, list what each gesture does now, and keep that list in the agent's brief.
|
|
61
|
+
- **Screen-sized labels** (sprites with `sizeAttenuation: false`) go into a registry at creation. Never `scene.traverse` every frame to find them.
|
|
62
|
+
- **Phones.** Pixel ratio capped at 2, `powerPreference: 'low-power'`, `PCFShadowMap` on touch devices (soft PCF on desktop), one shadow-casting light, instancing for repeated props (trees, lamps), and pause rendering when the tab is hidden.
|
|
63
|
+
- **Animated characters.** Clone with `SkeletonUtils.clone`. Use one `AnimationMixer` per character and crossfade clips (idle, walk, sprint, jump, fall, emote).
|
|
64
|
+
- **Labels must not collide** with fixed UI: test the tallest building's label against the segmented control at 1440×900 and 2000×1100.
|
|
65
|
+
|
|
66
|
+
## UI direction that the client approved (Apple HIG)
|
|
67
|
+
- Clarity: one purpose per screen; a large title of 34 px, body text of 17 px, `tabular-nums` for timers and scores.
|
|
68
|
+
- System font for the UI; one display font only for titles and game moments.
|
|
69
|
+
- Deference: neutral surfaces with one accent colour for primary actions, and no ornament.
|
|
70
|
+
- Depth: cards on a grouped background with soft shadows. Bottom sheets with a grabber for details. Blur only on controls that float over the 3D view.
|
|
71
|
+
- iOS patterns: inset grouped lists, segmented controls, and one primary button pinned at the bottom (`padding-bottom: max(16px, env(safe-area-inset-bottom))`).
|
|
72
|
+
- Motion: about 350–500 ms with `cubic-bezier(.32,.72,0,1)` and `scale(.97)` on press. Every tap gets feedback (sound, `navigator.vibrate(10)`).
|
|
73
|
+
- Thin line icons drawn as inline SVG. No emoji icons, no hype copy, no purple gradients, no fake stats.
|
|
74
|
+
- Login on a phone: the password field must stay visible above the keyboard. Keep the hero and the list short, and let Enter submit.
|
|
75
|
+
|
|
76
|
+
## Parallel agents
|
|
77
|
+
- First one agent builds the shell and one reference round end to end. Then one agent per remaining round, each editing only its own `rounds/<key>.js`.
|
|
78
|
+
If an agent needs a page change, it describes it in its report, and you apply it.
|
|
79
|
+
- The brief, as a file in the scratchpad: what the user asked (quoted), files to read first, the contract, the content rules, the "keep" list, the verification to run, and a word-capped report.
|
|
80
|
+
The report covers what was done, controls, case count, asset KB, weak spots, and the "what's new" lines.
|
|
81
|
+
- Tell every agent whether the site is live. On the real project, edits went public the moment they were saved, so "keep it working at every save" was in every brief.
|