picopilot 0.0.0 → 0.1.0

package/src/engine/skills/skills.test.ts

@@ -0,0 +1,376 @@
+import {execFileSync} from 'node:child_process';
+import {
+	existsSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	statSync,
+} from 'node:fs';
+import {homedir, tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {createCli} from '../../cli.js';
+import {installSkills, SKILL_NAMES, skillsSourceDir} from './index.js';
+
+/**
+ * Reads an authored skill's SKILL.md straight from the on-disk source dir, the
+ * same files incur's `include` glob ships. Skill GENERATION output is these
+ * files, so the generation tests assert against them directly.
+ */
+function readSkill(name: string): string {
+	return readFileSync(join(skillsSourceDir(), name, 'SKILL.md'), 'utf8');
+}
+
+describe('picopilot skills: generation output (the authored discipline skills)', () => {
+	it('ships exactly the named authored skills, each with valid frontmatter', () => {
+		expect([...SKILL_NAMES].sort()).toEqual(
+			[
+				'picopilot-art',
+				'picopilot-audio',
+				'picopilot-code',
+				'picopilot-debug',
+				'picopilot-overview',
+				'game-design-reference',
+				'game-jam',
+			].sort(),
+		);
+		for (const name of SKILL_NAMES) {
+			const md = readSkill(name);
+			// incur discovers a skill by its `name:` frontmatter line; a `description:`
+			// is what makes it load on-demand. Both must be present and match.
+			expect(md).toMatch(new RegExp(`^name:\\s*${name}$`, 'm'));
+			expect(md).toMatch(/^description:\s*.+/m);
+		}
+	});
+
+	it('game-design-reference is a USER-INVOKED reference body (no per-turn context load)', () => {
+		const md = readSkill('game-design-reference');
+		// The invocation stance: only game-design-reference disables model
+		// invocation, so it is reached by pointer (from game-jam), never fired on a
+		// vague trigger, and costs no context every turn. game-jam stays
+		// model-invoked (no such line).
+		expect(md).toMatch(/^disable-model-invocation:\s*true$/m);
+		expect(readSkill('game-jam')).not.toMatch(/^disable-model-invocation:/m);
+	});
+
+	it('game-design-reference carries the universal principles + method-not-menu originality', () => {
+		const md = readSkill('game-design-reference');
+		// Fairness: BOTH reachability AND the skipped hazard-avoidability check.
+		expect(md.toLowerCase()).toContain('reachability');
+		expect(md.toLowerCase()).toContain('avoidability');
+		// Human reaction budget in PICO-8's 30fps terms.
+		expect(md).toContain('200-300ms');
+		expect(md).toContain('frame-perfect');
+		// Visibility (draw what you spr()).
+		expect(md).toContain('spr(');
+		// Originality is a METHOD with a self-check, and lists NO concrete
+		// mechanics (the answer-menu trap). Assert the caveat that guards it.
+		expect(md.toLowerCase()).toContain('self-check');
+		expect(md.toLowerCase()).toMatch(/no (example |concrete )?mechanic/);
+		// Progression as a universal principle: a game GOES SOMEWHERE, expressed
+		// as a ladder of FORMS (ramp -> waves -> levels -> worlds). The situated
+		// "how far up given the clock" call lives in game-jam, not here.
+		expect(md.toLowerCase()).toContain('progression');
+		expect(md.toLowerCase()).toContain('goes somewhere');
+		expect(md.toLowerCase()).toContain('waves');
+		expect(md.toLowerCase()).toMatch(/worlds/);
+	});
+
+	it('game-jam carries the clock discipline and POINTS AT game-design-reference (does not re-teach it)', () => {
+		const md = readSkill('game-jam');
+		// Composition: it points at the reference body by name.
+		expect(md).toContain('game-design-reference');
+		// REGRESSION GUARD (see the FLIPRUN observation + re-grill): a
+		// disable-model-invocation reference skill is NOT auto-loaded by pi, so a
+		// bare-name "read and apply X" pointer gets SKIPPED (the agent never opens
+		// the file). The reliable pattern (Matt's, verified on pi + Claude Code) is
+		// an EXPLICIT relative path resolved against THIS skill's dir + an
+		// imperative to read/load it. Assert the pointer has both, so it never
+		// regresses to the weak wording that made the reference body unreachable.
+		expect(md).toContain('../game-design-reference/SKILL.md');
+		expect(md.toLowerCase()).toMatch(/\b(read|load)\b/);
+		// And game-design-reference stays user-invoked (the reason the explicit
+		// pointer is REQUIRED): if someone flips it to model-invoked, this pairing
+		// assumption changes and the pointer guard should be revisited.
+		expect(readSkill('game-design-reference')).toMatch(
+			/^disable-model-invocation:\s*true$/m,
+		);
+		// The jam-specific clock discipline (the slice/deepen/triage phases).
+		expect(md.toLowerCase()).toContain('playable slice');
+		expect(md.toLowerCase()).toContain('triage');
+		// The situated design calls the clock forces (jam-specific, live nowhere
+		// else): the dead state and the frame-perfect superhuman level.
+		expect(md.toLowerCase()).toContain('dead state');
+		expect(md).toContain('frame-perfect');
+		// Budget-scaled ambition (grilled: one skill, no per-tier files): scale to
+		// the clock, reach up the progression ladder as far as you can FINISH,
+		// deepen > polish on a long budget. Intent-framed, not a level-count menu.
+		expect(md.toLowerCase()).toContain('scale your ambition');
+		expect(md.toLowerCase()).toContain('progression ladder');
+		expect(md.toLowerCase()).toMatch(/finish/);
+		// It interprets the theme itself (decision B) and ships JAM.md.
+		expect(md).toContain('JAM.md');
+	});
+
+	it('picopilot-overview carries the #include discipline', () => {
+		const md = readSkill('picopilot-overview');
+		expect(md).toContain('#include main.lua');
+		expect(md).toContain('main.lua');
+		// Edit the Lua, never the binary sections (allow line wrapping between words).
+		expect(md).toMatch(/never\s+hand-write/i);
+		expect(md).toContain('__gfx__');
+	});
+
+	it('picopilot-code carries the token-breakdown discipline', () => {
+		const md = readSkill('picopilot-code');
+		expect(md).toContain('8,192');
+		expect(md).toContain('picopilot tokens');
+		expect(md).toContain('picopilot minify');
+		// A PICO-8 shorthand the skill teaches for reclaiming budget.
+		expect(md).toContain('+=');
+	});
+
+	it('picopilot-art carries the render→look→set→render loop AND the non-multimodal fallback', () => {
+		const md = readSkill('picopilot-art');
+		// The art loop.
+		expect(md).toContain('gfx render');
+		expect(md).toContain('gfx set');
+		expect(md).toContain('gfx show');
+		// The load-bearing non-multimodal fallback: view the PNG if you can read
+		// images, else reason over the grid.
+		expect(md.toLowerCase()).toContain('cannot read images');
+		expect(md.toLowerCase()).toMatch(/reason(ing)?\s+over the[\s\S]*grid/i);
+		// The gfx/map overlap smart-refuse discipline.
+		expect(md.toLowerCase()).toContain('overlap');
+		expect(md).toContain('allowMapOverlap');
+	});
+
+	it('picopilot-audio carries the picopilot-MML authoring model + the honest record-based render framing', () => {
+		const md = readSkill('picopilot-audio');
+		expect(md).toContain('picopilot-MML');
+		// ABC is explicitly NOT used.
+		expect(md).toContain('ABC');
+		// Music is assembled structurally from SFX references.
+		expect(md.toLowerCase()).toContain('structural');
+		// Honest scoping (ADR-0009): audio-to-WAV is a RECORDING, NOT an offline
+		// export, and needs a real audio session (a developer machine).
+		expect(md.toLowerCase()).toContain('recording');
+		expect(md.toLowerCase()).toContain('offline export');
+	});
+
+	it('picopilot-debug carries the static-gate + run loop and the dependency boundaries', () => {
+		const md = readSkill('picopilot-debug');
+		expect(md).toContain('picopilot verify');
+		expect(md).toContain('picopilot run');
+		expect(md).toContain('printh');
+		expect(md).toContain('gate-incapable');
+		expect(md).toContain('pico8-not-found');
+		expect(md).toContain('shrinko-not-found');
+	});
+});
+
+/**
+ * Recursively snapshots a directory tree as a sorted list of `relpath:mtimeMs`
+ * for files and `relpath/` for dirs, so a before/after comparison catches ANY
+ * new/removed entry AND any modified file. Returns `['<absent>']` when the dir
+ * does not exist (so "absent stays absent" is also asserted).
+ */
+function snapshot(root: string): string[] {
+	if (!existsSync(root)) return ['<absent>'];
+	const out: string[] = [];
+	const walk = (dir: string, rel: string) => {
+		for (const entry of readdirSync(dir, {withFileTypes: true}).sort((a, b) =>
+			a.name.localeCompare(b.name),
+		)) {
+			const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+			const abs = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				out.push(`${relPath}/`);
+				walk(abs, relPath);
+			} else {
+				// lstat, not stat: never follow a symlink out of the snapshotted tree.
+				out.push(
+					`${relPath}:${statSync(abs, {throwIfNoEntry: false})?.mtimeMs ?? 'gone'}`,
+				);
+			}
+		}
+	};
+	walk(root, '');
+	return out;
+}
+
+/**
+ * The REAL agent skill dirs this test must prove are byte-untouched. incur
+ * installs canonically to `~/.agents/skills` and symlinks detected non-universal
+ * agents (e.g. `~/.claude/skills`), so those are the dirs the isolation contract
+ * guards. Resolved from the real `homedir()` (which is what incur reads).
+ */
+const REAL_DIRS = [
+	join(homedir(), '.agents', 'skills'),
+	join(homedir(), '.claude', 'skills'),
+	join(homedir(), '.codex', 'skills'),
+	join(homedir(), '.cursor', 'skills'),
+];
+
+describe('picopilot skills: isolated --install-skills (the load-bearing shared-write test)', () => {
+	let target: string;
+	let before: Map<string, string[]>;
+
+	beforeEach(() => {
+		target = mkdtempSync(join(tmpdir(), 'picopilot-skills-install-'));
+		// Snapshot the REAL dirs before the install so we can prove they never moved.
+		before = new Map(REAL_DIRS.map((d) => [d, snapshot(d)]));
+	});
+
+	afterEach(() => {
+		try {
+			execFileSync('rm', ['-rf', target]);
+		} catch {
+			// ignore
+		}
+	});
+
+	it('installs into the redirected temp target, NOT a real dir', async () => {
+		// The lever: global=false + cwd=temp installs under <cwd>/.agents/skills.
+		const result = await installSkills({
+			cli: createCli(),
+			global: false,
+			cwd: target,
+		});
+
+		// Every named discipline skill landed (plus the per-command skills).
+		for (const name of SKILL_NAMES) {
+			expect(result.skills).toContain(name);
+			expect(
+				existsSync(join(target, '.agents', 'skills', name, 'SKILL.md')),
+			).toBe(true);
+		}
+		// Every reported canonical path is INSIDE the temp target.
+		for (const p of result.paths) {
+			expect(p.startsWith(target)).toBe(true);
+		}
+		// Any wired non-universal agent dir is also inside the temp target, never a
+		// real home dir (the symlinks go under cwd for a project install).
+		for (const a of result.agents) {
+			expect(a.path.startsWith(target)).toBe(true);
+		}
+	});
+
+	it('leaves the REAL agent skill dirs BYTE-UNTOUCHED', async () => {
+		await installSkills({cli: createCli(), global: false, cwd: target});
+
+		// The real dirs are identical before and after: no new entry, nothing
+		// modified, and an absent dir stays absent. This is the pollution guard.
+		for (const dir of REAL_DIRS) {
+			expect(snapshot(dir)).toEqual(before.get(dir));
+		}
+	});
+
+	it('a custom sourceDir proves the source is decoupled from the install target', async () => {
+		// Point the include SOURCE at a fixture with a single skill; install TARGET
+		// stays the temp dir. Only that fixture's authored skill (plus the
+		// per-command skills) should appear, proving cwd and source are independent.
+		const source = mkdtempSync(join(tmpdir(), 'picopilot-skills-src-'));
+		try {
+			const skillDir = join(source, 'picopilot-fixture');
+			execFileSync('mkdir', ['-p', skillDir]);
+			execFileSync('sh', [
+				'-c',
+				`printf '%s\\n' '---' 'name: picopilot-fixture' 'description: A fixture skill.' '---' '# fixture' > ${JSON.stringify(join(skillDir, 'SKILL.md'))}`,
+			]);
+
+			const result = await installSkills({
+				cli: createCli(),
+				global: false,
+				cwd: target,
+				sourceDir: source,
+			});
+
+			expect(result.skills).toContain('picopilot-fixture');
+			// The real authored discipline skills are NOT pulled in from this source.
+			expect(result.skills).not.toContain('picopilot-overview');
+			// Still installed into the temp target, and the real dirs stay untouched.
+			expect(
+				existsSync(
+					join(target, '.agents', 'skills', 'picopilot-fixture', 'SKILL.md'),
+				),
+			).toBe(true);
+			for (const dir of REAL_DIRS) {
+				expect(snapshot(dir)).toEqual(before.get(dir));
+			}
+		} finally {
+			execFileSync('rm', ['-rf', source]);
+		}
+	});
+
+	it('ships skill RESOURCE files, not just SKILL.md (incur 0.4.10 workaround)', async () => {
+		// incur's SyncSkills.sync copies only SKILL.md; installSkills backfills the
+		// sibling resources. The genre code references under
+		// picopilot-code/reference/ must reach the installed skill dir, or the
+		// SKILL.md's on-demand pointers dangle.
+		await installSkills({cli: createCli(), global: false, cwd: target});
+
+		const codeSkill = join(target, '.agents', 'skills', 'picopilot-code');
+		expect(existsSync(join(codeSkill, 'SKILL.md'))).toBe(true);
+		for (const res of [
+			'reference/README.md',
+			'reference/platformer.md',
+			'reference/puzzle-grid.md',
+			'reference/twin-stick-arcade.md',
+			'reference/top-down-adventure.md',
+			'reference/mode7-racing.md',
+			'reference/rpg-menus-dialog.md',
+		]) {
+			expect(existsSync(join(codeSkill, res))).toBe(true);
+		}
+		// The resource content is the authored source byte-for-byte (a real copy).
+		expect(
+			readFileSync(join(codeSkill, 'reference/platformer.md'), 'utf8'),
+		).toBe(
+			readFileSync(
+				join(skillsSourceDir(), 'picopilot-code', 'reference/platformer.md'),
+				'utf8',
+			),
+		);
+		// The real dirs stay untouched (resource copy respects isolation).
+		for (const dir of REAL_DIRS) {
+			expect(snapshot(dir)).toEqual(before.get(dir));
+		}
+	});
+
+	it('copies arbitrary nested resources from a custom source, isolated', async () => {
+		// A fixture skill with a nested resource proves the copy is general (not
+		// hard-coded to picopilot-code) and stays inside the temp target.
+		const source = mkdtempSync(join(tmpdir(), 'picopilot-skills-src-'));
+		try {
+			const skillDir = join(source, 'picopilot-fixture');
+			execFileSync('mkdir', ['-p', join(skillDir, 'reference', 'deep')]);
+			execFileSync('sh', [
+				'-c',
+				`printf '%s\n' '---' 'name: picopilot-fixture' 'description: A fixture skill.' '---' '# fixture' > ${JSON.stringify(join(skillDir, 'SKILL.md'))}`,
+			]);
+			execFileSync('sh', [
+				'-c',
+				`printf 'RES' > ${JSON.stringify(join(skillDir, 'reference', 'deep', 'note.md'))}`,
+			]);
+
+			await installSkills({
+				cli: createCli(),
+				global: false,
+				cwd: target,
+				sourceDir: source,
+			});
+
+			const installed = join(target, '.agents', 'skills', 'picopilot-fixture');
+			expect(existsSync(join(installed, 'SKILL.md'))).toBe(true);
+			expect(
+				readFileSync(join(installed, 'reference', 'deep', 'note.md'), 'utf8'),
+			).toBe('RES');
+			for (const dir of REAL_DIRS) {
+				expect(snapshot(dir)).toEqual(before.get(dir));
+			}
+		} finally {
+			execFileSync('rm', ['-rf', source]);
+		}
+	});
+});

package/src/engine/skills/skills.ts

@@ -0,0 +1,205 @@
+import {cpSync, existsSync, readdirSync} from 'node:fs';
+import {basename, dirname, join} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {Cli, SyncSkills} from 'incur';
+
+/**
+ * The engine behind `picopilot init --install-skills`: the ONE picopilot path
+ * that writes to a SHARED/GLOBAL location. incur's `skills add` defaults to a
+ * GLOBAL install (into `~/.agents/skills` plus symlinks into detected agent
+ * dirs like `~/.claude/skills`), so this module is where the work-contract's
+ * shared-write isolation obligation is discharged: every knob that decides the
+ * install TARGET (`global`, `cwd`) is a parameter a test can redirect to a temp
+ * dir, so installing skills can never pollute the real environment in tests.
+ *
+ * The install runs IN-PROCESS through incur's `SyncSkills.sync`. NOTE (incur
+ * 0.4.10): `SyncSkills.sync` / the `skills add` built-in resolve their target
+ * from `os.homedir()` and `process.env` captured AT MODULE LOAD, NOT from the
+ * `env` DI you can pass to `cli.serve(argv, { env })`, so overriding the serve
+ * env does NOT move the install target. The effective in-process lever is
+ * `global: false` + `cwd: <temp dir>`, which installs under `<cwd>/.agents/skills`
+ * (and `<cwd>/.claude/skills` etc.) and leaves the real dirs byte-untouched.
+ */
+
+/**
+ * The authored picopilot skills (US #20 discipline skills + the game skills),
+ * as SKILL.md files under {@link skillsSourceDir}. They load on-demand by
+ * concern and carry the hard-won workflow knowledge (the `#include` discipline,
+ * the token breakdown, the `gfx render`→look→`gfx set`→fix loop incl. the
+ * non-multimodal fallback, composing in picopilot-MML) so an agent gets it
+ * without bloating every turn.
+ *
+ * The GAME skills are a composed pair (grilled design in
+ * work/notes/ideas/game-jam-design-skill.md): `game-jam` (model-invoked, the
+ * clock+theme discipline) POINTS AT `game-design-reference` (a user-invoked
+ * reference body of universal design principles, `disable-model-invocation`, so
+ * it costs no per-turn context and is reached only by pointer, not fired on a
+ * vague trigger). Both ship engine-packaged here; `game-design-reference`'s
+ * CONTENT is engine-agnostic.
+ *
+ * They ship ALONGSIDE the per-command skills incur auto-generates from the
+ * command surface (`sync: { depth: 1 }`), pulled in via an `include` glob; the
+ * command surface is still growing, so the named discipline skills are authored
+ * rather than tied to a command-group shape that does not exist yet.
+ */
+export const SKILL_NAMES = [
+	'picopilot-overview',
+	'picopilot-code',
+	'picopilot-art',
+	'picopilot-audio',
+	'picopilot-debug',
+	'game-design-reference',
+	'game-jam',
+] as const;
+
+/**
+ * Resolves the on-disk directory that holds the authored `picopilot-*` SKILL.md
+ * files (`<packageRoot>/src/skills`). The files ship in the npm package (the
+ * package `files` includes `src`), so the same path works from the built
+ * `dist/` runtime and from `src/` under tsx: we walk up from THIS module to the
+ * package root (the nearest ancestor with a `package.json`) and join `src/skills`,
+ * rather than a `dist`-relative path that would not exist (SKILL.md is not
+ * compiled).
+ */
+export function skillsSourceDir(): string {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	const seen = new Set<string>();
+	while (!seen.has(dir)) {
+		seen.add(dir);
+		if (existsSync(join(dir, 'package.json'))) {
+			return join(dir, 'src', 'skills');
+		}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	// Fallback: two levels up from src/engine/skills is the package root.
+	return join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'skills');
+}
+
+/** One agent whose skill dir picopilot's install wired up (from incur's result). */
+export interface WiredAgent {
+	readonly agent: string;
+	readonly path: string;
+	readonly mode: string;
+}
+
+/** The outcome of installing picopilot's skills. */
+export interface InstallSkillsResult {
+	/** Canonical install paths (one per skill, under `<base>/.agents/skills`). */
+	readonly paths: string[];
+	/** Non-universal agents whose dirs were symlinked/copied to the canonical skills. */
+	readonly agents: WiredAgent[];
+	/** The skill names that were installed. */
+	readonly skills: string[];
+}
+
+/** Options controlling WHERE and HOW picopilot's skills are installed. */
+export interface InstallSkillsOptions {
+	/**
+	 * The picopilot CLI whose command surface the per-command skills are generated
+	 * from. Its command map (via {@link Cli.toCommands}) is handed to incur.
+	 */
+	readonly cli: Cli.Cli;
+	/**
+	 * Install globally (the real default, into `~/.agents/skills` + detected agent
+	 * dirs) when true; install project-locally (into `<cwd>/.agents/skills`) when
+	 * false. This is the shared-write isolation lever: tests pass `false`.
+	 */
+	readonly global: boolean;
+	/**
+	 * The install base for a project-local (`global: false`) install and, when a
+	 * non-universal agent is detected, the base its symlinks are written under.
+	 * Ignored for a global install (that goes to the real home). Tests point this
+	 * at a temp dir.
+	 */
+	readonly cwd?: string;
+	/**
+	 * Override the authored-skills source dir. Defaults to {@link skillsSourceDir}.
+	 * Exists so a test can prove isolation using its own fixture skills.
+	 */
+	readonly sourceDir?: string;
+}
+
+/**
+ * Installs picopilot's skills (the authored `picopilot-*` discipline skills plus
+ * the per-command skills incur generates from the CLI) via incur's
+ * `SyncSkills.sync`. This is the real work `init --install-skills` performs.
+ *
+ * The authored skills are pulled in with an ABSOLUTE `include` glob into
+ * {@link skillsSourceDir}, DECOUPLED from `cwd` on purpose: `cwd` selects the
+ * install TARGET, the include glob selects the skills SOURCE. That decoupling is
+ * what lets a test install to a temp `cwd` while still reading the real authored
+ * skills (or its own fixtures), the crux of the isolation contract.
+ */
+export async function installSkills(
+	options: InstallSkillsOptions,
+): Promise<InstallSkillsResult> {
+	const commands = Cli.toCommands.get(options.cli);
+	if (commands === undefined) {
+		throw new Error(
+			'installSkills: the given CLI has no command map (was it built by Cli.create?)',
+		);
+	}
+
+	const source = options.sourceDir ?? skillsSourceDir();
+
+	const result = await SyncSkills.sync('picopilot', commands, {
+		depth: 1,
+		description: 'An agent-first toolchain for PICO-8 game development.',
+		global: options.global,
+		cwd: options.cwd,
+		// Absolute glob → resolves against `source`, independent of `cwd`.
+		include: [join(source, '*')],
+	});
+
+	// Ship skill RESOURCE files (everything a skill dir carries besides SKILL.md).
+	// incur 0.4.10's SyncSkills.sync copies ONLY SKILL.md and drops sibling files
+	// (see work/notes/observations/incur-syncskills-drops-skill-resource-files.md),
+	// so genre code references under e.g. `picopilot-code/reference/` would never
+	// reach the installed skill. We backfill them here: for each installed skill
+	// path (canonical + each wired agent), copy the matching source skill's
+	// non-SKILL.md contents in. This stays inside the already-isolated installSkills
+	// seam, so the shared-write isolation test still governs it, and it becomes a
+	// no-op (safe to delete) once incur copies full skill dirs.
+	const installPaths = [...result.paths, ...result.agents.map((a) => a.path)];
+	for (const installedSkillDir of installPaths) {
+		copySkillResources(
+			join(source, basename(installedSkillDir)),
+			installedSkillDir,
+		);
+	}
+
+	return {
+		paths: result.paths,
+		agents: result.agents.map((a) => ({
+			agent: a.agent,
+			path: a.path,
+			mode: a.mode,
+		})),
+		skills: result.skills.map((s) => s.name),
+	};
+}
+
+/**
+ * Copies a source skill directory's RESOURCE files (everything except SKILL.md)
+ * into an already-installed skill directory. This is the workaround for incur
+ * 0.4.10 shipping only SKILL.md (see the observation referenced in installSkills):
+ * SKILL.md is left to incur (it is already written and may be transformed), and
+ * only the sibling resources are backfilled, recursively, preserving structure.
+ *
+ * Both the source skill and any resources are optional: a skill with no resource
+ * files, or a source dir that does not exist (a command-generated skill with no
+ * authored source), is a silent no-op. Nothing here reaches outside `destDir`,
+ * which is one of the install paths SyncSkills already chose, so it inherits the
+ * shared-write isolation of installSkills (tests redirect those paths to a temp).
+ */
+function copySkillResources(sourceSkillDir: string, destDir: string): void {
+	if (!existsSync(sourceSkillDir) || !existsSync(destDir)) return;
+	for (const entry of readdirSync(sourceSkillDir)) {
+		if (entry === 'SKILL.md') continue; // incur owns the manifest; do not clobber it
+		cpSync(join(sourceSkillDir, entry), join(destDir, entry), {
+			recursive: true,
+		});
+	}
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+import type {Cli} from 'incur';
+import {createCli} from './cli.js';
+
+export {createCli} from './cli.js';
+export {VERSION} from './version.js';
+
+/**
+ * The default CLI instance, exported for `incur gen` (typed CTAs) and for
+ * embedding picopilot as a Fetch API handler / MCP server.
+ */
+const cli: Cli.Cli = createCli();
+
+export default cli;

package/src/skills/game-design-reference/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: game-design-reference
+description: Reference body of universal game-design principles (fairness, human reaction budget, readability, visibility, originality method). A shared reference other skills point at (game-jam, and any make-a-game skill); not fired on its own.
+disable-model-invocation: true
+---
+
+# game design reference
+
+Universal principles of a GOOD game, true of any game regardless of engine, clock, or theme. This is a shared REFERENCE body: another skill (e.g. `game-jam`) points you here and you apply every principle below. It is engine-agnostic; where a check needs a concrete PICO-8 procedure (drive a cart, count frames), that lives in the loop skill `picopilot-debug` (playtest), which you follow the pointer into.
+
+The one failure mode that unites the traps below: **an agent playtests as a frame-perfect machine and never models a human player.** You can hit any button on the exact right frame and see every pixel, so a game that is fair-and-playable TO YOU can be unfair or impossible for a human. Every check here is you deliberately putting on the human's eyes and hands.
+
+## Fairness: never a dead state
+
+A game is UNFAIR when it can reach a state the player did nothing wrong to reach, from which EVERY available action leads to a loss. A death the player could not have avoided reads as the GAME cheating, not the player failing, and it damages fairness far more than a hard-but-fair challenge does. Fairness is "the player can always still win, even after a setback": from every state, at least one legal move is non-losing.
+
+This is distinct from DIFFICULTY. Hard is fine; a dead state punishes the player for the game's own design gap.
+
+**The self-check (the one that gets skipped).** When a game has HAZARDS plus LIMITED control (a few discrete actions), verify BOTH properties, not just the first:
+
+1. **Goal reachability** — from spawn/rest states, some sequence of actions reaches the objective. (Agents check this one.)
+2. **Hazard avoidability** — from EVERY state the player can settle/rest into, at least ONE available action is non-fatal. (Agents SKIP this one.) If a resting position exists where all actions force a loss, that is a DEAD STATE: a fairness defect. Fix the geometry (widen an exit, move the hazard, add a safe lane) so no such pocket exists.
+
+For a discrete-control game this is enumerable: drive the player into every corner/pocket it can settle in, then try EACH action and assert not-all-fatal. Do this with the playtest loop (`picopilot-debug`) deliberately, it will not happen by accident.
+
+## Reaction budget: a human is not frame-perfect
+
+Simple human reaction time is ~200-300ms (see a thing, press a button) and that is DETECTION only, before deciding what to do. At PICO-8's 30fps that is roughly **6-9 frames** just to react. So:
+
+- **Any required-input WINDOW narrower than ~6-9 frames is effectively frame-perfect** and unplayable by a human as a reaction (only as a memorised pattern).
+- **Do not tune difficulty against your own `--input` scripts.** If the ONLY way you can clear a level is a hand-timed frame sequence you authored, a human cannot clear it. That is the trap: you tuned against a frame-perfect player (yourself).
+- **Telegraph, then require.** Fast games stay fair by relying on PREDICTION: give a readable wind-up so the player acts on anticipation, not on a sub-reaction-time window. Difficulty should come from planning/prediction pressure, not from beating the reaction-time floor.
+
+**The self-check.** Before calling a level done, ask: could a HUMAN with ~250ms reaction clear this, relying on telegraphed anticipation rather than frame-perfect timing? If clearing it needs your exact scripted frames, widen the window or add telegraphing.
+
+## Visibility: the player must see the player
+
+If you `spr(n)` an entity, sprite n must actually be DRAWN (a non-empty sprite), or the entity is invisible and the game is unplayable however correct the logic. Prefer primitives (`circfill`, `rectfill`, `line`) for the player and key entities unless you have authored real sprites, primitives can never be an empty slot. The player, and every entity the player must track, must be visible and distinguishable on screen.
+
+## Readability and feedback
+
+The player must be able to READ the game state at a glance and get FEEDBACK for every action: what am I, what is a hazard, what is a goal, did my input register, did I score or get hit. Motion trails, colour contrast, a HUD, particles/shake/sfx on events, these are not polish for its own sake, they are how the player perceives the state they must act on.
+
+## Difficulty curve and progression
+
+A good game GOES SOMEWHERE: it escalates. Ramp difficulty by introducing or combining MECHANICS (a new hazard type, a new interaction) over the playthrough, not merely by piling more of the same obstacle. More-of-the-same reads as samey and does not deepen; a new wrinkle does. Aim for a difficulty ARC with a satisfying peak, not a flat loop. Keep the first contact with each new mechanic gentle enough to learn it before it is tested under pressure.
+
+Progression can take MANY FORMS, a ladder from cheapest to richest:
+
+1. **A difficulty ramp within one loop** (speed / spawn rate / hazard density rises as you play) — the smallest way to "go somewhere".
+2. **Escalating waves / rounds** (new hazard TYPES arrive in later waves, not just more) — deepens one screen without new scenes.
+3. **Discrete levels / stages** (hand-built rooms, each teaching or combining a mechanic) — a real authored arc.
+4. **Worlds / acts** (sustained progression across many levels, new mechanics unlocking) — the top of the ladder.
+
+Each rung "goes somewhere" more than the one below; each also costs more to build and finish. WHICH rung a given game should reach is not universal, it depends on how much you can build and FINISH (a rough over-reach loses to a finished smaller arc). Pick the highest rung you can complete well.
+
+## Originality: a method, not a menu
+
+Novelty is a real design quality and it is the axis judges cap hardest. But it cannot be handed to you as a list of mechanics, if it were, every game would converge on the same listed idea and it would be the list-writer's creativity, not yours. So this section teaches a METHOD to GENERATE and then TEST your own idea. It deliberately lists NO example mechanics. (If you are editing this skill: do not add concrete example mechanics here. A listed lever becomes the answer every agent copies, run after run, the exact trap this framing exists to avoid.)
+
+**Interrogate your idea (questions to ask about YOUR idea, not answers to copy):**
+
+- What is the OBVIOUS version of this theme, the first thing anyone would build? (Name it, so you can avoid it.)
+- Could you SUBVERT the expectation the theme sets, rather than meet it?
+- Could you INVERT the role, act on the world instead of the avatar, or control the thing usually controlled against you?
+- Could the CONSTRAINT itself become the mechanic, rather than a limit you work around?
+- Could two unrelated ideas COMBINE into something neither is alone?
+- Could you RECONTEXTUALISE a familiar mechanic into a setting that changes its meaning?
+
+**The self-check (load-bearing).** Before you commit to an idea: name the obvious version of this theme; is your idea just that with a reskin? If a judge (or player) has almost certainly seen this exact game before, go again. Commit only to an idea that passes this check, then build it well, a fresh idea executed roughly beats a stale idea executed perfectly.