@drawcall/create 0.0.0

package/dist/prompts.js

@@ -0,0 +1,138 @@
+import { ASSET_SURVEY_FILE, GOAL_FILE, PLAN_FILE, PROOF_DIR, README_FILE, TECH_SURVEY_FILE } from "./constants.js";
+// Shared quality philosophy, stated in the project's language (see LANGUAGE.md): a turn
+// either changes the product (build) or writes a record (think); a step is real only when
+// the product really does the thing when run; the goal must never be shrunk. Stated as a few
+// principles the harness applies by reasoning, not a checklist of concrete examples —
+// enumerated lists make the model anchor on the listed cases and go shallow on everything else.
+function buildPrinciples() {
+    return `Principles — apply them by reasoning about this goal, not by matching a checklist:
+1. Real, not nominal: a step is done only when the product actually does the thing when run. The right category being present is not done, and the goal must never be silently shrunk into a prototype.
+2. Fit the tools: the installed Drawcall skills and runtime packages are the default toolkit. Discover what is installed rather than assuming — read the installed skills' \`SKILL.md\` docs for the real API and examples before using one. For each need the work has, fit the right skill/package/asset and use its real API/exports/examples for its role; if nothing fits, name the fit-gap and its user-visible tradeoff rather than shipping a silent cheap substitute.
+3. Right feedback, right place: present state where the user perceives it and in the medium that suits it, and keep debug/instrumentation out of the default product view.
+4. See and judge your own work: the test that counts is observing the real running product — drive it, and watch and listen to clips and screenshots from the player's seat — and judging what you see and hear against the look and feel the goal commits to, then iterating until it actually reads right. Not internal counters, not source-file validity, and not mere presence: a part that runs without error but looks wrong, reads flat, sounds wrong, or feels off is not done.
+5. Things that move or act are embodied: whatever the user sees move, act, or react carries its motion/animation, its moment-to-moment behavior, and its on-entity feedback as parts of the feature, not as later polish. A controller or path or number is not the behavior; a model is not the animation.`;
+}
+// The anti-blind-spot move for planning/building: derive the concerns for each slice from the
+// goal instead of recognising them from a fixed list.
+function buildSliceMethod() {
+    return `Method — derive the concerns per slice instead of recognising them from a list: for every user-visible thing a slice introduces, of whatever kind, reason from the goal about what would make that specific thing feel real and complete, budget those concerns in the slice, then explicitly name whatever you are leaving unaddressed. Treat broad labels (combat, enemies, building, navigation, UI, audio, and so on) as prompts to decompose into the parts that thing actually needs — then group the parts that complete one capability into this turn's step and build them together as one provable whole, rather than fragmenting each into its own deferred step. Decomposing is to see the scope and budget it, not to multiply steps.`;
+}
+export function buildTemplatePrompt(userPrompt) {
+    return `Stay in the current directory.
+
+Goal: ${userPrompt}
+
+${buildPrinciples()}
+
+This directory already holds a scaffolded project (package.json, installed skills/packages).
+Use npx @drawcall/market to look for a reasonable starter that covers the requested experience.
+Read the Market workflow with \`npx @drawcall/market skill\` if needed, and search starters with commands shaped like \`npx @drawcall/market search "<query>" --type template --limit 3\`.
+Prefer a fitting starter or asset-backed starter over a from-scratch setup when it covers the requested experience.
+If one fits, apply it into this directory, merging it with what is already here and preserving the installed skills/packages, without creating a nested project.
+Do not choose a template that omits major requirements from the goal.
+If none fits, make no filesystem changes and exit successfully.
+Do not implement the app.`;
+}
+export function buildSurveyAssetsPrompt(userPrompt) {
+    return `Stay in the current project directory.
+
+Goal: ${userPrompt}
+
+You are surveying, not planning or building: catalogue the Market assets that already exist and fit this goal, so the goal and plan stages can draw on real options.
+
+Search and preview the Drawcall Market with \`npx @drawcall/market\` (the \`market\` skill doc has the commands and the asset types). Start from the user-visible experience, not from obvious nouns alone: include the things the player sees, hears, controls, collides with, collects, inhabits, and receives as moment-to-moment feedback. For each distinct need, find the assets that fit and judge fit from the real preview — metadata, screenshots, files — not the name.
+
+Before writing, cross-check the goal against the Market asset types that could carry it — templates, models, humanoid models and animations, textures, environments, sound effects, background music, and flipbooks. This is a coverage pass, not a checklist to pad the file: mention a type only when it serves this goal or when its absence creates a real gap. Pay special attention to asset needs that are easy to misclassify as "implementation": animation clips, surface materials, sky/HDR, continuous audio such as ambience or background music, one-shot sound effects, and visual feedback such as fire, impacts, magic, weather, UI/world pings, or explosions. When the goal needs both event feedback and ongoing mood, survey both; do not let sound effects stand in for music/ambience, or a visual effect stand in for its matching sound.
+
+Before finishing, check that each asset-shaped word or sensory promise in the goal has an entry or an explicit gap. If the goal names music, a storm, muzzle flashes, impacts, explosions, collectibles, a place type, a character type, or any similar visible/audible thing, the survey should either name fitting assets for it or say that Market has no fitting asset.
+
+Write your findings to ${ASSET_SURVEY_FILE} (scratch, not committed): one entry per user-visible need with the fitting asset(s), what each actually is, and the gaps where nothing fits. Keep it concrete and skimmable, e.g.:
+- Collectible / pickup feedback: \`pickups-coin@1.0.2\` plus a fitting pickup sound — low-poly gold disc and a short reward cue. Strong fit.
+- Large outdoor place: no fitting island terrain model found — gap; use terrain/material assets instead.`;
+}
+export function buildSurveyTechnologyPrompt(userPrompt) {
+    return `Stay in the current project directory.
+
+Goal: ${userPrompt}
+
+You are surveying, not planning or building: catalogue the installed technology that fits this goal, so the goal and plan stages can draw on what is real.
+
+This project ships with a set of installed agent skills — each a \`SKILL.md\` doc covering one capability — and a set of npm packages, and that set changes over time. Discover what is actually installed now rather than assuming or working from memory: list and read every installed skill's \`SKILL.md\`, and read package.json for the runtime packages. Skim them all first so you know the full toolkit before routing a single need — the skill you skip is the one a need belongs to. Each \`SKILL.md\` is the authority on what its technology does, when it fits, and its limits; for installed library packages, confirm the specific exports against the real types, which can lag the docs, and for technology a skill adds on demand (assets, optional packages) trust the \`SKILL.md\` and note it as an install-time addition. Follow each skill's own routing and limits — when a skill says to compose specific pieces or warns against a shortcut, do that rather than guessing a turnkey that conflicts.
+
+Decompose the goal into its concrete needs and map each to the technology that fits. Where no installed technology fits a need — often a game-system need like quests, inventory, AI, or a signature custom mechanic — name it as a fit-gap the build must implement itself, rather than forcing a poor fit.
+
+Write your findings to ${TECH_SURVEY_FILE} (scratch, not committed): one entry per need, with the fitting skill/package and the real API/exports/asset that serves it, or the gap where nothing fits. Keep it concrete and skimmable, e.g. one bullet per need:
+- <need>: <fitting skill/package> — <the real API/exports that matter> — strong fit, following the skill's recommended composition.
+- <need>: no installed technology fits — fit-gap, the build implements it.`;
+}
+export function buildGoalPrompt(userPrompt) {
+    return `Stay in the current project directory.
+
+Goal: ${userPrompt}
+
+${buildPrinciples()}
+
+Create ${GOAL_FILE}: a concrete, fixed picture of the finished game that every later turn builds toward. It is the target, not a plan or task list, and stays stable as the project grows.
+Ground it in what actually exists: read the surveys ${ASSET_SURVEY_FILE} and ${TECH_SURVEY_FILE} for the assets and technology that fit, and read ${README_FILE} for the current state — weighing how close that state already is to what the request wants. When ${README_FILE} shows a substantial, coherent game already in the same space as the request (an applied starter, not a bare scaffold), anchor the finished picture on that real implementation: take the scope and shape it has already settled as the substrate, and reach past it only for what the request genuinely needs and the current state does not yet deliver — rather than re-deriving an idealized version that re-opens settled scope or adds large systems the starter deliberately leaves out. The closer the current state already is to realizing the request, the more the goal is bound to it; a bare scaffold or a poor-fit starter binds it not at all, and the goal is then the full target the request deserves. Name the handful that define the look, feel, and mechanics (e.g. "low-poly style, terrain from asset A, props B/C, movement via skill D") — the defining choices, not a full asset manifest (the surveys already hold that). Where nothing fits a needed part, say so as a fit-gap rather than quietly dropping it.
+
+Write it the way a strong, short game design document reads — concrete, decisive, easy to picture — but as a layered design, not a flat list of headings. A game's design runs from the experience it is for at the top down to how each thing looks and feels in the player's hands at the bottom, and the levels are causal in both directions: the top decides why every lower thing exists, while the player meets the game from the bottom up — touching the feel of a single action first, and only through it sensing the experience you aimed at. So design top-down and keep each lower choice traceable to the level above (this enemy, this loop, this verb earns its place by serving the experience), and never stop at rules-on-paper — because the player lives at the bottom, the bottom must be drawn as concretely as the top.
+The levels below, with the questions that live at each, are context to reason from, not a template to fill or a checklist to tick. Reason from this specific game about which levels carry it and how deep each goes — a puzzler lives on its mechanics, an exploration game on its world and mood, an arcade game on feel and mastery, a story RPG on its characters and the plot and world they inhabit — and say plainly what you are deliberately keeping thin or absent, which is itself a design decision. Go as deep on the level a game lives on as that game needs: the depth a story game owes its characters and plot is the depth an action game owes its feel — do not let any one level default to thin because it is harder to write. Add a question a level needs that is not here.
+- Experience and fantasy (top — what the game is for): the core feeling and kind of fun it trades in (sensation, make-believe, drama, challenge and mastery, fellowship, discovery, expression, or pastime — name the one or two that are primary), who the player is and the fantasy they get to live, the premise and the hook that makes the player care, the handful of design pillars every lower choice must serve, and — beyond the first session — what would bring a player back. A game with none of this reads as a tech demo.
+- Loops and progression (how the experience is produced over time): the core loop stated as the one-sentence "what you do", the macro arc of a session and what makes one sitting feel complete, and how challenge, variety, and stakes build across it — the shape of the curve, not just "it gets harder". Commit to where the game's lasting richness comes from — mastery, systemic interaction, story, exploration, replay variety, atmosphere — and be honest about which are thin.
+- Systems and rules (the authored substrate): the player's verbs, the objectives, the resources and their economy, the boundaries, and the win and loss conditions where they exist — the rules that, set in motion, produce the loops above.
+- Entities and world (the concrete cast): the specific things that fill the game — the player, allies, enemies, obstacles, pickups — each as a presence with a role and a behavior rather than a prop, and the world or levels that hold them at a real scale, in numbers. Where the game lives on its fiction, this is also the level of the story and the people in it: the overall plot, each significant character's identity, motivation, and backstory, and the world's lore and the immersion it builds — written to the depth that game needs, not reduced to a one-line premise. Some games are essentially non-narrative or single-screen; say so plainly.
+- Feel and feedback (bottom — moment to moment, the micro loop): what the player sees, hears, and feels in the instant they act — embodiment, animation, game feel, audio, VFX — presented where the player perceives it. Feedback is part of the verb, not a later polish pass; a controller or a number is not the feel. For each thing that carries the game, say what it actually looks like and how it reads and behaves second-to-second, concrete enough to hold a screenshot against. But the still frame is not the whole of feel: some of what carries a game is continuous and not visual at all — above all the audio bed and the mood it sustains (music, ambience, the soundscape under the action), which no screenshot holds. Give it the same concreteness — what it sounds like and how it shifts with the game's state — and remember it when you set the real-done bar below, where it is judged by ear over a clip rather than by a frame.
+- Controls, camera, and onboarding (across the stack): the input scheme and perspective, how the player learns the verbs without a wall of tutorial, and how they can always tell what their current goal is.
+- Presentation and the ending: the player-facing states and the moments between them — the first-load screen the player meets while assets stream in (a loading screen carrying the game's identity and progress, never a blank canvas), title, pause, win and loss screens, replay — and the camera moves, cutscenes, and transitions that frame beats and carry the player between states; and how a session resolves, in success and in failure where the game can be lost.
+
+The document must contain a playthrough that grounds the whole design: a concrete, timed traversal from the player's seat ("on load …; a few seconds in …; a minute in …") that walks a real session to its terminal as a script, not a summary. Trace the arcs that actually matter for this game — a full successful run for certain, and the loss or failure path too where the game can be lost (a game that can be lost but cannot show its own loss is not finished); do not manufacture a failure arc for a game that has none. For each beat make three things concrete: what the player perceives and how they come to know what to do next (the signpost, prompt, marker, or feedback that motivates the action — never assume the player simply knows); what they do; and how the game responds, including the transitions — camera moves, cutscenes, screen and state changes — that carry them between moments. Track the player's state and growing sense of progress so it reads as a lived session, not a feature list. This playthrough is part of the goal document, not the proof step below.
+
+Plus, for this pipeline, Real-done — the bar later turns hold themselves to: the handful of things that make this game genuinely good, not merely present, each one paired with how a build-turn confirms it in the running product, so the bar and its check live together rather than as two separate lists. Write each as an aspect plus its validation. The aspect is in look-and-feel terms concrete enough to judge by eye or ear — "the map reads as <its intended place> from the player's seat", not "a map exists"; "the enemy reads as <its intended threat> as it moves and takes a hit", not "the enemy is implemented". The validation is the observation that settles that aspect, made by watching and listening to the running product from the player's seat and not assembled as evidence for someone else: a runtime fact that is plainly true or false (a hit drops health; death shows the loss screen), or a qualitative read of a screenshot or clip — by eye ("the night forest looks stunning, a place you'd want to linger") or by ear ("the score swells into the fight and drops to a hush when it ends") — or whatever mix the aspect needs; judge continuous and audio aspects over a clip, not a still frame. Cover the game this way, and treat the playthrough(s) above — reproduced end-to-end in the running product — as the overarching check, not only isolated slices.
+
+Do not create ${PLAN_FILE} and do not implement the app.`;
+}
+export function buildPlanPrompt(userPrompt) {
+    return `Stay in the current project directory.
+
+Goal: ${userPrompt}
+
+${buildPrinciples()}
+
+Ground the plan in what is real: ${GOAL_FILE} is the fixed goal, ${README_FILE} the claimed current state, and the scratch surveys ${ASSET_SURVEY_FILE} and ${TECH_SURVEY_FILE} the already-gathered map of what fits. Verify the actual project state before writing — the surveys can be stale.
+
+Write ${PLAN_FILE}: the ordered steps from the current state to the goal. A step is one coherent vertical slice of the real product that a single build-turn — one harness execution — can build and verify end to end, and that leaves the game more playable than before. The first step is already such a slice, not setup alone.
+
+Size each step to the most a single build-turn can confidently build and stand behind in one go, and group into it the features that complete one testable capability together. Resolve the real tension between two failure modes: a pure one-mechanic-at-a-time slice proves out every turn but tends to build throwaway scaffolding (a stand-in you later discard, a thin version you rewrite) and pay for the same area twice; a pure feature-batch implements each feature once but is too big to build and prove in a turn. Aim for the middle — group the features that naturally belong to one capability so each is implemented once, against its real collaborators, while the step still fits and proves in one turn. A system that only proves out with another (shooting needs something to shoot, loot needs someone to drop it) is usually a cue to group the two into one step, not to split them behind a stand-in: prefer building a feature with its real collaborators when they fit the same turn. Reach for a deliberate stand-in only when the real collaborator genuinely cannot fit the same turn and the stand-in is cheap and minimal — never substantial scaffolding you will throw away. Build shared foundations right the first time: the ECS spine, the controller/camera rig, the audio system and other substrate should be established correctly when first needed and reused — not built thin and "consolidated" in a later refactor (a planned pure-refactor step is a sign a foundation was under-built, and a build-turn spent on rework is a step the budget can't afford). A step that cannot exist until an earlier one lands comes after it. Size each step to one build-turn's worth, and let the plan run exactly as long as the real distance from the current state to the goal demands — no longer. The build-turn budget is a ceiling, not a quota to fill: when the current state already realizes most of the goal the plan is correspondingly short — as few as a single step — and you neither pad it with generic polish or re-verification of what already works nor stretch a small delta to resemble a full build; when the distance is large, use as many right-sized steps as it takes, preferring a few whole steps to a long trail of fragments and never a step too large for one turn to finish and stand behind.
+
+A slice is the whole of the thing it introduces, not its mechanic alone. Reason from the goal about what makes each one real in the player's hands — its animation and feedback, how the player comes to know what to do and can see their current goal, the transitions and screens that frame it — and carry those into the same step, never deferring them to a later polish the embodiment principle forbids. Which of these a slice lives on depends on what it is; weigh them, do not tick them off a list.
+
+Some of the game is not a vertical slice at all — the continuous, cross-cutting layers no single feature owns: the audio bed (ambience and music), the atmospheric look (lighting mood and the postprocessing pass), the shared HUD frame, and the first-load/loading screen. Place these deliberately instead of letting them fall to a final step a stalled plan may never reach. Introduce a layer's foundation in the first step where the player would feel its absence — world ambience and music with the first explorable world, the look pass once there is a scene to grade, the loading screen in the very first step (any real build loads assets before it can show anything, so a blank canvas is felt from the start) — and extend it as the game grows. Foundational mood is part of the feel the goal commits to, not last-minute polish; a game that reaches its last planned step before it has any music or atmosphere was planned in the wrong order.
+
+Decide; do not hedge. A build-turn ignores "optional", "if available", "maybe", and "if it proves too heavy", so make the call now — pick the approach, or, where something genuinely may not exist, name it as a fit-gap with the tradeoff it forces. Every line should be something a build-turn must act on.
+
+For each step name:
+- Outcome — what the player can newly do, see, and feel in the running product.
+- Fit — the skills, packages, and assets that serve it, with the real APIs/exports/asset ids that matter, and any fit-gap with its tradeoff. Recommend the technology and content; leave the file layout to the build-turn.
+- Gate — how the build-turn confirms the slice is genuinely done: not evidence written for someone else but the check it runs on itself, across every quality the slice needs — that it behaves correctly when run, that it is built soundly enough to carry the later slices, and that it reads right on screen when judged by eye against the goal's real-done bar, iterated until it does. Name the runtime checks, screenshots, or clips that would settle each.
+
+Update ${README_FILE} to reflect the current state, the planned scope, and the gaps that remain.
+Do not implement the plan.`;
+}
+export function buildBuildPrompt(userPrompt, turn) {
+    return `Stay in the current project directory.
+
+Goal: ${userPrompt}
+
+Build turn ${turn}.
+
+${buildPrinciples()}
+
+${buildSliceMethod()}
+
+Use ${README_FILE} as the claimed current state, ${GOAL_FILE} as the fixed goal, and ${PLAN_FILE} as the plan.
+Take the first remaining ${PLAN_FILE} step as this turn's task and build the whole of it — the grouped features it names — with the fitting skills/packages/assets, allowing only the small prerequisites or repairs that make the step actually work. A right-sized step is one turn's work, so complete it rather than fragmenting it.
+Only if the step genuinely cannot fit one turn, split off the smallest coherent remainder as a single new ${PLAN_FILE} step (not a trail of fragments), and finish the rest now. Do not add pure-refactor, cleanup, or "consolidate the architecture" steps that don't advance the product — build the foundation correctly here, which means laying the code out as cohesive modules from the first turn (follow each skill's recommended file layout, such as the ecs skill's one-file-per-component and one-file-per-system split, rather than piling the game into one growing main file) instead of leaving rework for a future turn the budget can't afford. When a feature needs a collaborator that exists later in the plan, prefer pulling it forward into this step over building a throwaway stand-in you will discard.
+Prove the result with a proof-run that actually launches and drives the real running repo this turn — a written description is never a substitute for a run. The proof is a machine-produced artifact saved under \`${PROOF_DIR}/\` (gitignored scratch): a screenshot or clip captured from the running app, or — if you cannot view images — a recorded runtime-state dump that asserts the real-done runtime facts, each produced by the command you actually ran rather than authored by hand. Look at the screenshots/clips from the player's seat and judge them against the goal's real-done bar, iterating on the build until it reads right; a prose "verification" note with no run behind it does not satisfy the gate. Then close or rewrite the ${PLAN_FILE} step to reflect what is actually proven; if a turn only proved part of the step, keep the unproven parts as first-class remaining steps rather than caveats.
+If real findings change the project understanding, update ${GOAL_FILE} lightly and honestly.
+Finally, update ${README_FILE} so it truthfully describes the new proven state, what changed, what remains in ${PLAN_FILE}, and any remaining gaps.`;
+}

package/dist/scaffold.d.ts

@@ -0,0 +1,15 @@
+import { type HarnessName } from "./constants.js";
+import { type CommandRunner } from "./subprocess.js";
+export declare function generateProjectName(): string;
+export declare function initGitRepo(cwd: string, runner: CommandRunner): Promise<void>;
+export declare function commitAll(cwd: string, runner: CommandRunner, message: string): Promise<void>;
+export declare function initNpmProject(cwd: string, _runner: CommandRunner): Promise<void>;
+export declare function ensureProjectGitignore(cwd: string): Promise<void>;
+export declare function ensureNpmrc(cwd: string): Promise<void>;
+export declare function ensureBaseProjectDirectories(cwd: string): Promise<void>;
+export declare function installSkills(cwd: string, harness: HarnessName, runner: CommandRunner): Promise<void>;
+export declare function installDependencies(cwd: string, runner: CommandRunner): Promise<void>;
+export declare function ensureStateReadme(cwd: string): Promise<void>;
+export declare function ensureLocalCliShims(cwd: string): Promise<void>;
+export declare function ensureMarketCliShim(cwd: string): Promise<void>;
+export declare function ensureActaCliShim(cwd: string): Promise<void>;

package/dist/scaffold.js

@@ -0,0 +1,220 @@
+import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { GITIGNORE_ENTRIES, PACKAGES, SKILLS } from "./constants.js";
+import { assertExitCode } from "./subprocess.js";
+export function generateProjectName() {
+    return `dc-${randomBytes(3).toString("hex")}`;
+}
+export async function initGitRepo(cwd, runner) {
+    await assertExitCode(runner({ command: "git", args: ["init"], cwd }), "failed to initialise git repository");
+}
+export async function commitAll(cwd, runner, message) {
+    await assertExitCode(runner({ command: "git", args: ["add", "-A"], cwd }), "failed to stage changes");
+    await assertExitCode(runner({ command: "git", args: ["commit", "--allow-empty", "-m", message], cwd }), "failed to commit changes");
+}
+export async function initNpmProject(cwd, _runner) {
+    const packageJsonPath = join(cwd, "package.json");
+    if (existsSync(packageJsonPath))
+        return;
+    await writeFile(packageJsonPath, `${JSON.stringify({
+        name: toPackageName(basename(cwd)),
+        version: "1.0.0",
+        private: true,
+        // Seed runnable scripts so every project is launchable from turn 1 (Vite is the pinned
+        // bundler). Build turns serve via `npm run dev` and bundle via `npm run build`; without
+        // these, weaker harnesses ship a project with no documented way to run the game.
+        type: "module",
+        scripts: {
+            dev: "vite",
+            build: "vite build",
+            preview: "vite preview"
+        }
+    }, null, 2)}\n`);
+}
+function toPackageName(name) {
+    const normalized = name
+        .toLowerCase()
+        .replace(/[^a-z0-9._~-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return normalized || "drawcall-project";
+}
+export async function ensureProjectGitignore(cwd) {
+    const gitignorePath = join(cwd, ".gitignore");
+    const existing = existsSync(gitignorePath) ? await readFile(gitignorePath, "utf8") : "";
+    const existingEntries = new Set(existing
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith("#")));
+    const missingEntries = GITIGNORE_ENTRIES.filter((entry) => !existingEntries.has(entry));
+    if (missingEntries.length === 0)
+        return;
+    const prefix = existing.trimEnd();
+    const nextContent = [prefix, ...missingEntries].filter(Boolean).join("\n") + "\n";
+    await writeFile(gitignorePath, nextContent);
+}
+// The curated package set pins a recent `three`, but some Drawcall packages declare peer ranges
+// that lag a minor or two (e.g. @drawcall/flipbook peers an older three). The scaffold's own
+// install passes `--legacy-peer-deps`, but later installs — a harness running `npm install`, or
+// `market install` applying a template — run plain and would abort on the first peer mismatch.
+// A persisted `.npmrc` makes the whole project tolerant so those installs don't veto a pinned
+// version over a peer-range lag.
+export async function ensureNpmrc(cwd) {
+    const npmrcPath = join(cwd, ".npmrc");
+    const existing = existsSync(npmrcPath) ? await readFile(npmrcPath, "utf8") : "";
+    if (/^\s*legacy-peer-deps\s*=/m.test(existing))
+        return;
+    const prefix = existing.trimEnd();
+    const nextContent = [prefix, "legacy-peer-deps=true"].filter(Boolean).join("\n") + "\n";
+    await writeFile(npmrcPath, nextContent);
+}
+export async function ensureBaseProjectDirectories(cwd) {
+    for (const directoryName of ["src", "public"]) {
+        const directory = join(cwd, directoryName);
+        await mkdir(directory, { recursive: true });
+        const placeholder = join(directory, ".gitkeep");
+        if (!existsSync(placeholder))
+            await writeFile(placeholder, "");
+    }
+}
+// Our harness names don't all match the `skills` CLI's agent ids.
+const SKILLS_AGENT = {
+    opencode: "opencode",
+    codex: "codex",
+    claude: "claude-code",
+    pi: "pi",
+    gemini: "gemini-cli",
+    // The skills CLI has no dedicated grok agent; "universal" installs to .agents/skills, which
+    // grok discovers. Verify skill discovery in grok's e2e run and adjust if it misses them.
+    grok: "universal",
+    // Likewise no dedicated forge agent; "universal" (.agents/skills) is the portable target.
+    // Verify forge actually discovers the installed skills in its e2e run and adjust if it misses.
+    forge: "universal"
+};
+export async function installSkills(cwd, harness, runner) {
+    for (const skill of SKILLS) {
+        await assertExitCode(runner({
+            command: "npx",
+            args: ["--yes", "skills", "add", skill, "-y", "--agent", SKILLS_AGENT[harness]],
+            cwd
+        }), `failed to install skill ${skill}`);
+    }
+}
+export async function installDependencies(cwd, runner) {
+    // This is a fixed, curated set of packages we install together; their peer ranges drift
+    // independently (e.g. a runtime that pins an older `three` minor), and modern npm aborts the
+    // whole install on the first peer mismatch. We don't want a generated project to fail to
+    // scaffold over a peer-range lag in one package, so we install the set as-specified and let
+    // the pinned versions stand rather than letting peer resolution veto them.
+    await assertExitCode(runner({ command: "npm", args: ["install", "--legacy-peer-deps", ...PACKAGES], cwd }), "failed to install dependencies");
+    await ensureLocalCliShims(cwd);
+}
+// Called after the template stage: an applied starter may already ship a README, so this only
+// creates a minimal state-record when none exists. The fixed goal lives in GOAL.md; the plan
+// lives in PLAN.md.
+export async function ensureStateReadme(cwd) {
+    const readmePath = join(cwd, "README.md");
+    if (existsSync(readmePath))
+        return;
+    await writeFile(readmePath, `# Project State
+
+This is the state-record: what the product actually is right now. The fixed goal
+lives in GOAL.md; the plan toward it lives in PLAN.md once planning has run.
+
+## Verified State
+
+- Nothing verified yet — the project was just scaffolded.
+
+## Next Step
+
+- Survey the fitting installed skills, packages, and Market assets, then plan and build the first real slice toward the full goal without shrinking it into a prototype.
+
+## Proof Log
+
+- No proof-run has been recorded yet.
+`);
+}
+// --- Installed-package shims -------------------------------------------------
+// The @drawcall/acta and @drawcall/market packages ship CLIs/install logic that
+// assume a different layout than a freshly-generated project. These helpers
+// patch the installed copies in node_modules so their bins resolve locally.
+export async function ensureLocalCliShims(cwd) {
+    await ensureActaCliShim(cwd);
+    await ensureMarketCliShim(cwd);
+}
+export async function ensureMarketCliShim(cwd) {
+    const packageRoot = join(cwd, "node_modules", "@drawcall", "market");
+    await rewriteMarketInstallRoot(join(packageRoot, "dist", "install.js"));
+    await rewriteMarketInstallRoot(join(packageRoot, "src", "install.ts"));
+}
+export async function ensureActaCliShim(cwd) {
+    const packageRoot = join(cwd, "node_modules", "@drawcall", "acta");
+    const devShim = join(packageRoot, "src", "cli", "dev.ts");
+    const sourceCli = join(packageRoot, "src", "cli", "index.js");
+    const distCli = join(packageRoot, "dist", "cli", "index.js");
+    const packageJsonPath = join(packageRoot, "package.json");
+    const binShim = join(cwd, "node_modules", ".bin", "acta");
+    if (!existsSync(distCli))
+        return;
+    await mkdir(dirname(sourceCli), { recursive: true });
+    await writeFile(sourceCli, "import '../../dist/cli/index.js';\n");
+    if (existsSync(devShim)) {
+        await writeFile(devShim, "#!/usr/bin/env node\nimport '../../dist/cli/index.js';\n");
+        await chmod(devShim, 0o755);
+    }
+    await rewriteActaPackageBin(packageJsonPath);
+    await rewriteActaPackageEntrypoint(packageJsonPath);
+    await mkdir(dirname(binShim), { recursive: true });
+    await rm(binShim, { force: true });
+    await writeFile(binShim, "#!/usr/bin/env node\nimport '../@drawcall/acta/dist/cli/index.js';\n");
+    await chmod(binShim, 0o755);
+}
+async function rewriteActaPackageBin(packageJsonPath) {
+    if (!existsSync(packageJsonPath))
+        return;
+    const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    const existingBin = packageJson.bin && typeof packageJson.bin === "object" ? packageJson.bin : {};
+    packageJson.bin = { ...existingBin, acta: "dist/cli/index.js" };
+    await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
+}
+async function rewriteActaPackageEntrypoint(packageJsonPath) {
+    if (!existsSync(packageJsonPath))
+        return;
+    const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    packageJson.main = "dist/index.js";
+    packageJson.types = "dist/index.d.ts";
+    packageJson.exports = {
+        ...(packageJson.exports ?? {}),
+        ".": {
+            types: "./dist/index.d.ts",
+            import: "./dist/index.js"
+        }
+    };
+    await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`);
+}
+async function rewriteMarketInstallRoot(filePath) {
+    if (!existsSync(filePath))
+        return;
+    const source = await readFile(filePath, "utf8");
+    const replacement = `export async function findInstallRoot(cwd = process.cwd()) {
+    const start = path.resolve(cwd);
+    let dir = start;
+    while (true) {
+        if (await isFile(path.join(dir, 'package.json'))) {
+            return dir;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return start;
+}
+
+async function downloadAssets`;
+    const patched = source.replace(/export async function findInstallRoot[\s\S]*?\n}\n\n?async function downloadAssets/, replacement);
+    if (patched !== source) {
+        await writeFile(filePath, patched);
+    }
+}

package/dist/subprocess.d.ts

@@ -0,0 +1,21 @@
+import { type SpawnOptions } from "node:child_process";
+export type CommandInvocation = {
+    command: string;
+    args: string[];
+    cwd: string;
+    timeoutMs?: number;
+};
+export type CommandResult = {
+    exitCode: number;
+    timedOut?: boolean;
+};
+export type CommandRunner = (invocation: CommandInvocation) => Promise<CommandResult>;
+export type CommandExists = (command: string, env: NodeJS.ProcessEnv) => Promise<boolean>;
+export type SubprocessRunnerOptions = Pick<SpawnOptions, "stdio" | "env"> & {
+    killGraceMs?: number;
+    logFile?: string;
+};
+export declare function createSubprocessRunner(options?: SubprocessRunnerOptions): CommandRunner;
+export declare function buildSubprocessEnv(cwd: string, baseEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function isCommandAvailable(command: string, env?: NodeJS.ProcessEnv): Promise<boolean>;
+export declare function assertExitCode(run: Promise<CommandResult>, message: string): Promise<void>;

package/dist/subprocess.js

@@ -0,0 +1,117 @@
+import { spawn } from "node:child_process";
+import { createWriteStream } from "node:fs";
+import { delimiter, dirname, join, resolve } from "node:path";
+import which from "which";
+import { CliError, TIMEOUT_EXIT_CODE, TIMEOUT_KILL_GRACE_MS } from "./constants.js";
+export function createSubprocessRunner(options = { stdio: "inherit" }) {
+    return (invocation) => runSubprocess(invocation, options);
+}
+function runSubprocess({ command, args, cwd, timeoutMs }, options) {
+    return new Promise((resolveResult, reject) => {
+        // A separate process group lets a timeout kill the whole child tree at once.
+        const detached = process.platform !== "win32";
+        // When a log file is set, capture all child output into it and keep the
+        // terminal clean for the progress note; otherwise stream straight through.
+        const logStream = openSessionLog(options.logFile, [command, ...args]);
+        const child = spawn(command, args, {
+            cwd,
+            detached,
+            env: buildSubprocessEnv(cwd, options.env ?? process.env),
+            stdio: logStream ? ["ignore", "pipe", "pipe"] : (options.stdio ?? "inherit")
+        });
+        if (logStream) {
+            child.stdout?.pipe(logStream, { end: false });
+            child.stderr?.pipe(logStream, { end: false });
+        }
+        let timedOut = false;
+        let killTimer;
+        let timeout;
+        if (timeoutMs !== undefined) {
+            timeout = setTimeout(() => {
+                timedOut = true;
+                const notice = `[drawcall-create] ${command} timed out after ${Math.ceil(timeoutMs / 1000)}s`;
+                if (logStream)
+                    logStream.write(`${notice}\n`);
+                else
+                    console.error(notice);
+                killChildProcess(child.pid, detached, "SIGTERM");
+                const grace = options.killGraceMs ?? TIMEOUT_KILL_GRACE_MS;
+                killTimer = setTimeout(() => killChildProcess(child.pid, detached, "SIGKILL"), grace);
+            }, timeoutMs);
+        }
+        // The child sits in its own process group, so terminal signals never reach it directly.
+        const forwardSignal = (signal) => {
+            killChildProcess(child.pid, detached, signal);
+            process.exit(signal === "SIGINT" ? 130 : 143);
+        };
+        process.on("SIGINT", forwardSignal);
+        process.on("SIGTERM", forwardSignal);
+        const cleanup = () => {
+            if (timeout)
+                clearTimeout(timeout);
+            if (killTimer)
+                clearTimeout(killTimer);
+            process.off("SIGINT", forwardSignal);
+            process.off("SIGTERM", forwardSignal);
+            logStream?.end();
+        };
+        child.once("error", (error) => {
+            cleanup();
+            reject(error);
+        });
+        child.once("exit", (code, signal) => {
+            cleanup();
+            if (timedOut)
+                return resolveResult({ exitCode: TIMEOUT_EXIT_CODE, timedOut: true });
+            resolveResult({ exitCode: signal ? 1 : (code ?? 1), timedOut: false });
+        });
+    });
+}
+export function buildSubprocessEnv(cwd, baseEnv = process.env) {
+    const projectParent = dirname(resolve(cwd));
+    const localBin = join(resolve(cwd), "node_modules", ".bin");
+    const existingCeiling = baseEnv.GIT_CEILING_DIRECTORIES;
+    const existingPath = baseEnv.PATH;
+    return {
+        ...baseEnv,
+        PATH: existingPath ? `${localBin}${delimiter}${existingPath}` : localBin,
+        GIT_CEILING_DIRECTORIES: existingCeiling
+            ? `${projectParent}${delimiter}${existingCeiling}`
+            : projectParent
+    };
+}
+export async function isCommandAvailable(command, env = process.env) {
+    const resolved = await which(command, {
+        nothrow: true,
+        path: env.PATH,
+        pathExt: env.PATHEXT
+    });
+    return resolved !== null;
+}
+export async function assertExitCode(run, message) {
+    const { exitCode } = await run;
+    if (exitCode !== 0)
+        throw new CliError(`${message} (exit code ${exitCode})`);
+}
+function openSessionLog(logFile, command) {
+    if (logFile === undefined)
+        return undefined;
+    const stream = createWriteStream(logFile, { flags: "a" });
+    stream.write(`\n$ ${command.join(" ")}\n`);
+    return stream;
+}
+function killChildProcess(pid, detached, signal) {
+    if (!pid)
+        return;
+    if (process.platform === "win32") {
+        // Signals only reach the direct child (often a cmd shim); taskkill tears down the tree.
+        spawn("taskkill", ["/pid", String(pid), "/T", "/F"], { stdio: "ignore" }).unref();
+        return;
+    }
+    try {
+        process.kill(detached ? -pid : pid, signal);
+    }
+    catch {
+        // The process may have exited between the timeout and kill attempt.
+    }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@drawcall/create",
+  "version": "0.0.0",
+  "type": "module",
+  "description": "Create projects with an installed local harness.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/drawcall-ai/create.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "drawcall-create": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "commander": "^14.0.3",
+    "which": "^6.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.21",
+    "@types/which": "^3.0.4",
+    "prettier": "3.8.4",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json && node -e \"require('fs').chmodSync('dist/cli.js', 0o755)\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  }
+}