@turri-dev/cli 0.1.13-next.9fe9bb8 → 0.1.14-next.3e3ff53

package/dist/extension.d.ts

@@ -24,7 +24,11 @@ dialogs?: AskUserIO): AskUser;
  * pick from, several at once, "Something else…" to type instead, "Chat about this" to talk it over in
  * the chat first - so a question with a handful of answers is picked, not typed.
  */
-export declare function chatAskUserTool(dialogs?: AskUserIO): ReturnType<typeof createAskUserTool>;
+/**
+ * ask_user, for the conversation. `afterAnswer` may add to what an answer tells the model - a skill the person picked,
+ * to start at once.
+ */
+export declare function chatAskUserTool(dialogs?: AskUserIO, afterAnswer?: (answer: string) => string | undefined): ReturnType<typeof createAskUserTool>;
 /**
  * What a host that runs turri's conversation itself - a desktop app, an editor - is told and asked, where the terminal
  * would draw: the conversation's jobs and its work loop as they are made and as they change, and the dialogs its

package/dist/extension.js

@@ -25,6 +25,7 @@ import { createDeployState, createDeployTools } from "./release-tools.js";
 import { runReleaseAgent } from "./release-agent.js";
 import { createSteeringStore, EVERY_MODULE, moduleNameOf, queueSectionOf, steeringFor } from "./regenerate/steer.js";
 import { askedForCommandLine, refusal, selfInvocation, TOOLS_NOT_CLI } from "./self-invocation.js";
+import { NEW_PROJECT } from "./new-project.js";
 import { describeChoices, describeResolution, modelFor, resolveModel } from "./regenerate/engine.js";
 import { checkPlainFile, checkPlainTargets, formatCheckResults } from "./plain/check.js";
 import { whyFailed } from "./regenerate/diagnose-job.js";
@@ -57,7 +58,7 @@ import { describeStdlib } from "./stdlib.js";
 import { peekKeyListener, runAsk } from "./ask.js";
 import { QuestionDialog } from "./question-dialog.js";
 import { registerStacks } from "./stacks.js";
-import { catalogueLine, createCommandGate, discoverSkills, leftOutNote, startedByCommandOnly } from "./skills.js";
+import { catalogueLine, chosenCommand, createCommandGate, startPicked, discoverSkills, leftOutNote, startedByCommandOnly } from "./skills.js";
 import { supersededByTurri } from "./chat-skills.js";
 import { conversationIdentity } from "./identity.js";
 import { setSurface, surfaceOf } from "./surface.js";
@@ -170,7 +171,11 @@ function hookPeekKey(ctx) {
  * pick from, several at once, "Something else…" to type instead, "Chat about this" to talk it over in
  * the chat first - so a question with a handful of answers is picked, not typed.
  */
-export function chatAskUserTool(dialogs) {
+/**
+ * ask_user, for the conversation. `afterAnswer` may add to what an answer tells the model - a skill the person picked,
+ * to start at once.
+ */
+export function chatAskUserTool(dialogs, afterAnswer) {
     let conversation;
     const tool = createAskUserTool((request) => (conversation !== undefined ? askUserVia(conversation, () => { }, undefined, dialogs)(request) : Promise.resolve("No user is available to answer.")), undefined, undefined, undefined, "reply");
     return {
@@ -181,7 +186,10 @@ export function chatAskUserTool(dialogs) {
         ],
         async execute(...args) {
             conversation = args[4];
-            return tool.execute(...args);
+            const result = await tool.execute(...args);
+            const answer = result.details?.answer;
+            const note = answer !== undefined && answer !== "" ? afterAnswer?.(answer) : undefined;
+            return note !== undefined ? { ...result, content: [...result.content, { type: "text", text: note }] } : result;
         },
     };
 }
@@ -313,7 +321,7 @@ function turriExtension(pi, host) {
             }
         }
         return {
-            systemPrompt: conversationSystemPrompt(event.systemPrompt, host, [TOOLS_NOT_CLI, projectConfigBlock(cwd), machineBlock(cwd, machine.now()), rulesBlock()]),
+            systemPrompt: conversationSystemPrompt(event.systemPrompt, host, [TOOLS_NOT_CLI, NEW_PROJECT, projectConfigBlock(cwd), machineBlock(cwd, machine.now()), rulesBlock()]),
         };
     });
     // The conversation's agent does not run turri again through its shell, unless the person
@@ -433,7 +441,17 @@ function turriExtension(pi, host) {
     registerBranding(pi, discoveredSkills);
     registerInterviewLog(pi);
     registerJobTools(pi, jobs, cwd);
-    registerCheckPlain(pi, cwd, host.dialogs);
+    // The skills the person starts themselves - brood, spawn, bud: each has its command, and cultivate starts it only
+    // once its command is typed, or picked among the options the conversation offers with ask_user.
+    const gate = createCommandGate();
+    // A skill picked is started at once, with what the person asked for: they never type its command after picking it.
+    registerCheckPlain(pi, cwd, host.dialogs, (answer) => {
+        const chosen = chosenCommand(answer, discoveredSkills.skills);
+        if (chosen === undefined)
+            return undefined;
+        gate.typed(chosen);
+        return startPicked(chosen, lastUserMessage);
+    });
     registerRegenerate(pi, cwd, jobs);
     registerDrift(pi, cwd, jobs);
     registerGlimpse(pi, cwd, jobs);
@@ -449,10 +467,8 @@ function turriExtension(pi, host) {
         return;
     const catalogue = skills.map(catalogueLine).join("\n");
     const pendingNote = leftOutNote(discoveredSkills);
-    // The skills the person starts themselves - brood, spawn, bud: each has its command, and cultivate starts it only
-    // once its command is typed. The command puts what was typed in the chat, as the person's message, for the model to
-    // run it with what follows as its context.
-    const gate = createCommandGate();
+    // The command puts what was typed in the chat, as the person's message, for the model to run it with what follows as
+    // its context.
     for (const skill of skills.filter((s) => s.commandOnly)) {
         pi.registerCommand(skill.name, {
             description: `Start ${skill.name}${skill.steps.length > 1 ? ` - ${skill.steps.map((step) => step.name).join(" → ")}` : ""}: /${skill.name} [what you want]`,
@@ -472,7 +488,7 @@ function turriExtension(pi, host) {
         promptSnippet: "cultivate: run a gated skill - its steps and review gates enforced by turri",
         promptGuidelines: [
             "When a request matches a skill listed in cultivate's description, call cultivate instead of doing the work yourself. Doing it by hand skips the review gates.",
-            "A skill marked as started only by the person runs only from its command: a message that is its command - /spawn a small server - is the person starting it, so call cultivate for it at once, with what follows the command as context. Never call cultivate for one otherwise; tell them to type its command.",
+            "A skill marked as started only by the person runs only from its command: a message that is its command - /spawn a small server - is the person starting it, and so is an option starting with it that they picked in your ask_user - /brood - an interview. Call cultivate for it at once, with what they said as context. Never call cultivate for one otherwise; for a new project, offer the choice as <new-project> says.",
             // pi lists .agents/skills among its own skills too: read and followed by hand, a skill's gates would be skipped.
             "A skill cultivate lists may also be among your own skills, from the project's .agents/skills: run it with cultivate all the same, never by reading its SKILL.md and following it.",
             "cultivate returns the reviewed artifact and a trace of every gate decision. Report the artifact to the user; do not rewrite it.",
@@ -2063,9 +2079,9 @@ function jobLines(all) {
  * so it needs no external tool, no API key and no credits - and it is the only honest way
  * to answer "is this spec valid?" without generating anything.
  */
-function registerCheckPlain(pi, cwd, dialogs) {
+function registerCheckPlain(pi, cwd, dialogs, afterAnswer) {
     pi.registerTool(checkPlainTool(cwd));
-    pi.registerTool(chatAskUserTool(dialogs));
+    pi.registerTool(chatAskUserTool(dialogs, afterAnswer));
     // The web, for the conversation too - a library's documentation, an API, an error; curl is its
     // bash. Run here, like the rendering agents' (see render/web.ts).
     for (const tool of createWebTools())

package/dist/new-project.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Starting a project from the conversation: the person says what they want built - "create a small server in Java
+ * Spring Boot" - and the chat offers the three ways to start it: brood's interview, spawn's quick start, or writing the
+ * ***plain itself, here, with no skill. An option picked that starts with a skill's command starts that skill, as if
+ * typed (`chosenCommand` in skills.ts).
+ */
+export declare const NEW_PROJECT: string;

package/dist/new-project.js

@@ -0,0 +1,37 @@
+/**
+ * Starting a project from the conversation: the person says what they want built - "create a small server in Java
+ * Spring Boot" - and the chat offers the three ways to start it: brood's interview, spawn's quick start, or writing the
+ * ***plain itself, here, with no skill. An option picked that starts with a skill's command starts that skill, as if
+ * typed (`chosenCommand` in skills.ts).
+ */
+export const NEW_PROJECT = [
+    "<new-project>",
+    "When the person asks for new software / project ",
+    "and there is no ***plain module for it yet, or they ask for a new project, ask them first how to start it, with",
+    "ask_user: one question, these three options, word for word, so they know the skills are there:",
+    `- "${"/brood - an interview: the stack, the testing and every feature settled with you, each answer regenerated"}"`,
+    `- "${"/spawn - something running in minutes: the quick start, asking only what your message leaves open"}"`,
+    `- "${"Just do it - no skill: I write it here and start regenerating"}"`,
+    "Picked /brood or /spawn: the answer starts it - call cultivate for it at once, with what they said as its context,",
+    "never asking them to type its command. Do not ask when their",
+    "message says already - they typed the command, or said to just build it, with no skill, without questions: then",
+    "start it yourself. Started yourself, how soon the first pulse starts, and something they can try, come first:",
+    "1. The stack: the one they named; otherwise one of the standard library's that this machine can build - common,",
+    "   simple - said in a line. A stack named in a language the machine lacks is written all the same: tell them what to",
+    "   install, and that turri doctor checks it. Read the stack's template, its language's and its kind's common first.",
+    "2. One module - a .plain file in the project's root, named after what it is (server.plain) - importing the stack and",
+    "   writing only what the module needs beyond it. Two side by side, each on its stack, only when it needs two stacks.",
+    "3. config.turri.yaml: module: the new file, and conformance-tests: false unless they asked for conformance tests.",
+    "   What a config there already settles - a stack, a script, conformance - is kept, not chosen again.",
+    "4. The unit testing script: keep one turri already finds; otherwise run cultivate with implement-unit-testing-script",
+    "   for the stack's language. Conformance tests asked for: their ***test reqs*** - the stack's conformance template -",
+    "   and cultivate with implement-conformance-testing-script.",
+    "5. The first functional spec: the smallest thing that runs and shows something - the server answers GET / with the",
+    "   app's name, the CLI prints its usage. validate, fix what it finds, and regenerate at once.",
+    "6. While it regenerates: the main thing they described, on its happy path, and at most one more - each a functional",
+    "   spec, with its concepts - then validate and regenerate again. Only what they described: they named only the kind of",
+    "   software, write none, and invite them to say what it does. No validation or edge cases yet.",
+    "Then hand over in a few lines: what you chose, what is regenerating, and the next slices you would write - they say",
+    "go on, or what to change, and every change after is ***plain you write and regenerate.",
+    "</new-project>",
+].join("\n");

package/dist/setup.d.ts

@@ -35,6 +35,7 @@ export declare function checkSandbox(wall?: Wall, platform?: NodeJS.Platform): C
 export declare function checkProject(project: string, machine?: {
     has?: (command: string) => boolean;
     exists?: (path: string) => boolean;
+    jdk?: () => boolean;
 }): Check[];
 /**
  * In a project: each model its config names - with the stack chosen, that stack's over it - tried with one short

package/dist/setup.js

@@ -66,7 +66,7 @@ export function checkSandbox(wall = sandboxAvailable(), platform = process.platf
  */
 export function checkProject(project, machine = {}) {
     const checks = [];
-    for (const { module, needs, missing } of stackOnMachine(project, machine.has)) {
+    for (const { module, needs, missing } of stackOnMachine(project, machine.has, machine.jdk)) {
         if (needs.length === 0)
             continue;
         checks.push(missing.length === 0

package/dist/skills.d.ts

@@ -42,3 +42,13 @@ export declare function createCommandGate(): {
 };
 /** What cultivate says of a command-only skill the person did not start. */
 export declare function startedByCommandOnly(name: string): string;
+/**
+ * What the model is told when the person picked a skill: start it now, with what they asked for - word for word, as the
+ * message that set off the question - so they never type its command after picking it.
+ */
+export declare function startPicked(name: string, request: string): string;
+/**
+ * The command-only skill an answer picks: an option offered to the person that starts with its command - `/brood - an
+ * interview` - is the person starting it, as if they typed it.
+ */
+export declare function chosenCommand(answer: string, skills: ReadonlyArray<Pick<FoundSkill, "name" | "commandOnly">>): string | undefined;

package/dist/skills.js

@@ -61,8 +61,8 @@ export function discoverSkills(packageRoot, projectDir) {
 /** A skill's line in cultivate's list: a project's says so, and where it is. */
 export function catalogueLine(skill) {
     const whose = skill.origin === "turri" ? "" : ` (this project's, ${skill.origin.project})`;
-    // One the person starts themselves: the model points them to its command rather than running it.
-    const byCommand = skill.commandOnly ? ` Started only by the person, with /${skill.name}: never run it unasked - when it fits, tell them to type /${skill.name}.` : "";
+    // One the person starts themselves - typed, or picked among the options the model offers: never run unasked.
+    const byCommand = skill.commandOnly ? ` Started only by the person, with /${skill.name} or by picking it when you offer it with ask_user: never run it unasked.` : "";
     return `- ${skill.name}${whose}: ${skill.description}${byCommand}`;
 }
 /** What is said under the list about the skills it leaves out. */
@@ -88,5 +88,22 @@ export function createCommandGate() {
 }
 /** What cultivate says of a command-only skill the person did not start. */
 export function startedByCommandOnly(name) {
-    return `Not started: ${name} is started only by the person, with /${name}. If it fits what they want, tell them to type /${name} - with what they want after it, if they like.`;
+    return `Not started: ${name} is started only by the person, with /${name} or by picking an option starting /${name} that you offer them with ask_user. For a new project, ask them as <new-project> says; otherwise do what they asked yourself, in the conversation.`;
+}
+/**
+ * What the model is told when the person picked a skill: start it now, with what they asked for - word for word, as the
+ * message that set off the question - so they never type its command after picking it.
+ */
+export function startPicked(name, request) {
+    const asked = request.trim();
+    return (`They picked ${name}, and it may start now: call cultivate with skill "${name}" at once, before anything else, and never ask them to type /${name}. ` +
+        `Pass as its context everything they have told you${asked !== "" ? `, starting with what they asked for, word for word: ${JSON.stringify(asked)}` : ""}.`);
+}
+/**
+ * The command-only skill an answer picks: an option offered to the person that starts with its command - `/brood - an
+ * interview` - is the person starting it, as if they typed it.
+ */
+export function chosenCommand(answer, skills) {
+    const typed = /^\s*\/([\w-]+)/.exec(answer)?.[1];
+    return skills.find((skill) => skill.commandOnly && skill.name === typed)?.name;
 }

package/dist/stack.d.ts

@@ -19,8 +19,11 @@ export declare function projectImplementationReqs(project: string): Array<{
     module: string;
     reqs: string[];
 }>;
-/** What a project's modules need of this machine, and which of it the machine lacks. */
-export declare function stackOnMachine(project: string, has?: (command: string) => boolean): Array<{
+/**
+ * What a project's modules need of this machine, and which of it the machine lacks - `has` finding a command, and on
+ * macOS a JDK behind `java` (`toolchainCheck`), asked at most once.
+ */
+export declare function stackOnMachine(project: string, has?: (command: string) => boolean, jdk?: () => boolean): Array<{
     module: string;
     needs: StackNeed[];
     missing: StackNeed[];
@@ -34,6 +37,11 @@ export declare const STDLIB_LANGUAGES: Array<{
     language: string;
     commands: string[];
 }>;
+/**
+ * Whether a toolchain's command is really there: `has` finds it - and Java has a JDK behind it as well, for macOS keeps a
+ * `/usr/bin/java` that only asks to install one.
+ */
+export declare function toolchainCheck(has: (command: string) => boolean, jdk?: () => boolean): (command: string) => boolean;
 /** Which of the standard library's languages this machine can build and test now, and which it lacks a command of. */
 export declare function languagesOnMachine(has?: (command: string) => boolean): {
     ready: typeof STDLIB_LANGUAGES;

package/dist/stack.js

@@ -57,11 +57,16 @@ export function projectImplementationReqs(project) {
 }
 /** Whether a command is on this machine's PATH. */
 const onPath = (command) => onThisMachine(command) !== undefined;
-/** What a project's modules need of this machine, and which of it the machine lacks. */
-export function stackOnMachine(project, has = onPath) {
+/**
+ * What a project's modules need of this machine, and which of it the machine lacks - `has` finding a command, and on
+ * macOS a JDK behind `java` (`toolchainCheck`), asked at most once.
+ */
+export function stackOnMachine(project, has = onPath, jdk = jdkHere) {
+    let found;
+    const here = toolchainCheck(has, () => (found ??= jdk()));
     return projectImplementationReqs(project).map(({ module, reqs }) => {
         const needs = stackOf(reqs.join("\n"));
-        return { module, needs, missing: needs.filter((need) => !need.commands.some(has)) };
+        return { module, needs, missing: needs.filter((need) => !need.commands.some(here)) };
     });
 }
 /**
@@ -76,17 +81,18 @@ export const STDLIB_LANGUAGES = [
     { language: "Rust", commands: ["cargo"] },
     { language: "Java", commands: ["java"] },
 ];
+/** Whether this machine has a JDK behind `java`: anywhere but macOS, java found says so; on macOS, `java_home` finding one. */
+function jdkHere() {
+    return process.platform !== "darwin" || spawnSync("/usr/libexec/java_home", [], { stdio: "ignore" }).status === 0;
+}
 /**
- * Whether a toolchain's command is really there: on the PATH - and Java on macOS, which keeps a `/usr/bin/java` that only
- * asks to install a JDK, by `java_home` finding one.
+ * Whether a toolchain's command is really there: `has` finds it - and Java has a JDK behind it as well, for macOS keeps a
+ * `/usr/bin/java` that only asks to install one.
  */
-function toolchainHere(command) {
-    if (!onPath(command))
-        return false;
-    if (command === "java" && process.platform === "darwin")
-        return spawnSync("/usr/libexec/java_home", [], { stdio: "ignore" }).status === 0;
-    return true;
+export function toolchainCheck(has, jdk = jdkHere) {
+    return (command) => has(command) && (command !== "java" || jdk());
 }
+const toolchainHere = toolchainCheck(onPath);
 /** Which of the standard library's languages this machine can build and test now, and which it lacks a command of. */
 export function languagesOnMachine(has = toolchainHere) {
     const ready = STDLIB_LANGUAGES.filter(({ commands }) => commands.every(has));

package/docs/authoring-plain.md

@@ -122,7 +122,7 @@ The ones that shape \*\*\*plain most:
 
 ## Writing \*\*\*plain with turri
 
-In a conversation (`turri`), say what you want and the matching skill runs - but the three that start a project or a feature you start yourself, by their commands: `/brood`, `/spawn` or `/bud`, with what you want after it. Two build a project from scratch, and write each \*\*\*plain change as a git diff that is built in the background the moment it is written. `brood` interviews you one question at a time and writes \*\*\*plain as you answer; `spawn`, its quick twin, gets something running as soon as it can - the smallest thing that runs first, then the product a slice at a time - asking only what your message leaves open:
+In a conversation (`turri`), say what you want and the matching skill runs - but the three that start a project or a feature you start yourself, by their commands: `/brood`, `/spawn` or `/bud`, with what you want after it. Asked for new software without one - `create a small server in Java Spring Boot` - turri offers `/brood`, `/spawn` or `Just do it`, with no skill; a skill picked there starts at once with what you asked for, and Just do it starts the project in the conversation as `spawn` would, writing the module, its config and its unit testing script, then the smallest thing that runs, regenerated at once, and the first slices of what you described (see [using turri](using.md)). Two build a project from scratch, and write each \*\*\*plain change as a git diff that is built in the background the moment it is written. `brood` interviews you one question at a time and writes \*\*\*plain as you answer; `spawn`, its quick twin, gets something running as soon as it can - the smallest thing that runs first, then the product a slice at a time - asking only what your message leaves open:
 
 | skill | phases | how a \*\*\*plain change is written |
 | --- | --- | --- |
@@ -145,13 +145,13 @@ Every skill in `genome/skills/` can be run from a conversation; most are also us
 
 | to… | skills |
 | --- | --- |
-| start a project | `brood`, `spawn` |
+| start a project | `brood`, `spawn` - or ask, and choose `Just do it` for no skill |
 | make rough \*\*\*plain build | `mature` |
 | add to \*\*\*plain | `bud`, `add-functional-spec`, `add-functional-specs`, `add-concept`, `add-implementation-requirement`, `add-test-requirement`, `add-acceptance-test`, `add-resource`, `add-template` |
 | check what is written | `analyze-if-func-spec-too-complex`, `analyze-2-func-specs`, `analyze-func-specs`, `resolve-section-ownership` |
 | fix what is written | `break-down-func-spec`, `resolve-spec-conflict`, `debug-specs` |
-| restructure modules | `create-import-module`, `create-requires-module`, `refactor-module`, `consolidate-concepts` |
-| set up the project to build | `implement-unit-testing-script`, `implement-conformance-testing-script`, `check-plain-env` |
+| restructure modules | `refactor-module`, `consolidate-concepts` |
+| set up the project to build | `implement-unit-testing-script`, `implement-conformance-testing-script` |
 
 `debug-specs` is the one for a running application that misbehaves: it reads the generated code to find the cause, traces it back to \*\*\*plain, and fixes only the `.plain` files.
 

package/docs/installation.md

@@ -54,7 +54,7 @@ In a project - a folder with `config.turri.yaml` (or the old `config.yaml`) or `
 
 | what | |
 | --- | --- |
-| each module's toolchains | what its implementation reqs name - Python, Node, Java, Go, Rust, C/C++, Zig, ... - against this machine's PATH: the agents use this machine's toolchains and install none, so a missing one is yours to install |
+| each module's toolchains | what its implementation reqs name - Python, Node, Java, Go, Rust, C/C++, Zig, ... - against this machine's PATH - and Java against a JDK, for macOS keeps a `/usr/bin/java` that only asks to install one: the agents use this machine's toolchains and install none, so a missing one is yours to install |
 | the testing scripts | what in them this machine does not have: a program named by its whole path that is not here (a macOS-only `/usr/libexec/java_home` on Linux), a toolchain they run that is not on the PATH |
 | the models | each model `config.turri.yaml` names - `harness-model`, `coding-model`, `judge-model`, every role under `models:` - sent one short request through [pi](https://pi.dev), with the credentials turri's agents will use, for any provider [pi](https://pi.dev) supports. One that answers is ready; for one that does not, it says what the provider said and what to do: the credentials [pi](https://pi.dev) reads for that provider (`AWS_PROFILE` and `AWS_REGION` for Amazon Bedrock, `OPENAI_API_KEY`, `/login`, ...), model access in the Bedrock console, the closest model ids [pi](https://pi.dev) knows for one it does not. `--harness-model`, `--coding-model` (`--model`) and `--judge-model` name models as the config's keys, as `turri regenerate` reads them - checked in a project or not. `--no-models` skips it |
 

package/docs/skills-and-gates.md

@@ -37,7 +37,7 @@ metadata:
 
 A skill declares its steps with a `## Steps` section whose `###` headings are the steps; without it the whole skill is one step, which is what most skills are. Steps are never inferred from `###` headings elsewhere in the body - prose skills are full of those. Each gate becomes a conditional edge after its step; a single-step skill is gated by naming the skill itself. None of the skills turri ships declares a gate today - `brood`'s phases end on the person's confirmation alone - but a project's own skill can.
 
-`command-only: true` under `metadata:` keeps a skill from the model: it is started only by the person, with its slash command - `/brood`, `/spawn` and `/bud` are. turri registers the command for every such skill, the project's own too. Typed, the command puts what was typed in the chat as the person's message, and lets `cultivate` start the skill once; the run starting uses that up, so the model cannot start it again later on its own. Without the command, `cultivate` refuses it and the model is told to name the command to the person instead - the skill's line in `cultivate`'s list says so too.
+`command-only: true` under `metadata:` keeps a skill from the model: it is started only by the person, with its slash command - `/brood`, `/spawn` and `/bud` are. turri registers the command for every such skill, the project's own too. Typed, the command puts what was typed in the chat as the person's message, and lets `cultivate` start the skill once - and so does an option starting with the command, `/brood - an interview`, picked in the conversation's `ask_user`, which is how the chat offers `/brood`, `/spawn` or starting a project itself with no skill (`chosenCommand` in `src/skills.ts`, `src/new-project.ts`). The answer tells the model to call `cultivate` for it at once, with the person's request word for word as its context (`startPicked`), so they never type the command after picking it; the run starting uses that up, so the model cannot start it again later on its own. Without either, `cultivate` refuses it and the model is told how the person starts it - for a new project, by the choice it offers; the skill's line in `cultivate`'s list says so too.
 
 `paced: false` under `metadata:` lets a skill write \*\*\*plain changes one after another on its own: `change_plain` otherwise refuses a new change until the user has answered a question since the last one - one answer, one change, as an interview writes them. `spawn` is unpaced: the tool tells it so, and after each change to write the next at once, not to carry on with an interview it does not have.
 

package/docs/using.md

@@ -9,7 +9,9 @@ turri
 
 That is [pi](https://pi.dev), with turri's tools, skills and themes loaded - `turri` alone, or with [pi](https://pi.dev)'s options (`turri -c`, `turri --harness-model <m>`). It opens with turri's own banner - the jellyfish it is named after, regenerating until the conversation fills the screen: a pixel polyp on the sea floor grows into the jellyfish - a bell from pink down to indigo, an orange gut, neon tentacles - which swims a while, sinks back to the floor, and the polyp grows again, round and round: a picture in a terminal that shows images (Kitty, Ghostty, WezTerm, Warp, iTerm2), and drawn at a third of the size in half blocks in any other, tmux included (`src/jellyfish.ts` draws it, ported from the design system's pixel kit, `scripts/jellyfish-frames.mjs` writes the pictures) - turri's version (and, run from a clone, the commit it is on, and whether the clone has changes) and where its settings are changed - and only when something is wrong, skills that failed to load or agents' commands less fenced than they should be - rather than [pi](https://pi.dev)'s startup header and resource list; `turri --verbose` shows those too. [pi](https://pi.dev)'s "Update Available" notice is left out - turri's [pi](https://pi.dev) is a pinned dependency `pi update` never touches - and the terminal's tab reads `🪼 turri - <folder>`, not [pi](https://pi.dev)'s `π`. Talk to it: ask it to add a feature to \*\*\*plain, regenerate a module, fix a module's \*\*\*plain. It decides which skill or tool applies - but not *how* a skill runs: `cultivate` hands the work to the gated runner, which owns the steps, the gates and the judges (see [skills and gates](skills-and-gates.md)).
 
-Three skills you start yourself, by their commands - turri never starts them on its own, and says which to type when one fits: `/brood`, `/spawn` and `/bud`, each with what you want after it - `/spawn a URL shortener in Go`. The skills that build from scratch:
+To start a project, just say what you want - `create a small server in Java Spring Boot` - and turri asks how to start it, with three choices: `/brood`, the interview; `/spawn`, the quick start; or `Just do it`, no skill. A skill picked there starts at once, with what you asked for as its context - nothing to type again; saying so in your message - `just build it`, or the command itself - skips the question. Just do it starts the project in the conversation: turri takes the stack you named, or chooses one this machine can build, and says it in a line; writes the module importing the stack from the standard library, `config.turri.yaml` (conformance tests off unless you ask for them) and the unit testing script (with `implement-unit-testing-script`, unless there is one); then the smallest thing that runs, regenerated at once, and while it regenerates the main thing you described and at most one more, on their happy path - nothing you did not describe. You say `go on`, or what to change, and every change after is \*\*\*plain it writes and regenerates (`src/new-project.ts`).
+
+Three skills you start yourself, by their commands or by picking them when turri offers them - it never starts them on its own: `/brood`, `/spawn` and `/bud`, each with what you want after it - `/spawn a URL shortener in Go`. The skills that build from scratch:
 
 | skill | how it works |
 | --- | --- |

package/genome/rules/import-modules.md

@@ -11,6 +11,7 @@ When creating or editing a `.plain` file that uses `import` or is intended to be
 - It must **not** contain `***functional specs***`
 - It must **not** use `requires` in its frontmatter
 - It may optionally `import` other import modules for layered reuse
+- A project's import modules live in `template/`, which imports resolve from: `import: [shared_api]` is `template/shared_api.plain`, the `template/` prefix left out
 
 ## What import does
 - `import` pulls in `***definitions***`, `***implementation reqs***`, and `***test reqs***` from the target module

package/genome/rules/integration-embedded.md

@@ -46,7 +46,7 @@ This keeps the integration self-contained in one directory the user can `cd` int
 
 Run host discovery **before** the first interview question. Treat the results as ground truth for everything that follows.
 
-1. **Locate the host's `.plain` setup (if any).** Look for an existing `.plain` file or directory, a `plain_modules/`, a `resources/`, and a `test_scripts/`. If the host already has a `.plain` setup, **adopt it verbatim**: the new integration module lands inside the existing `plain_source_dir` and `requires` the relevant base module (use `create-requires-module`). Do not create a parallel layout.
+1. **Locate the host's `.plain` setup (if any).** Look for an existing `.plain` file or directory, a `plain_modules/`, a `resources/`, and a `test_scripts/`. If the host already has a `.plain` setup, **adopt it verbatim**: the new integration module lands inside the existing `plain_source_dir` and `requires` the relevant base module (following `requires-modules.md`). Do not create a parallel layout.
 2. **Read every existing integration in the host.** For each one, extract: intent and scope, host base class / interface / protocol the integration subclasses or implements, package path and naming convention, configuration pattern (env vars, settings module, secret manager), error / exception hierarchy, logging / metrics / tracing conventions, testing pattern (live vs recorded vs mocked, fixture location, conformance-test layout). The new integration must follow the same patterns unless the user explicitly opts out.
 3. **Capture findings in the `host-codebase` concept.** Cite the existing integration by file path so the reasoning is auditable. The concept holds, as facts:
    - Host codebase root (absolute or project-relative path)

package/genome/skills/break-down-func-spec/SKILL.md

@@ -180,7 +180,7 @@ Define the component concept in `***definitions***` (via `add-concept`) before t
 - A :Report: is exported to PDF using :PdfRenderer:, embedding charts rendered from :Report: data.
 ```
 
-The extracted component spec and the rewritten original must together still cover 100% of the original functionality (step 6): the original must **reference** the component, never re-describe it. Keep the component's technology and architecture choices in `***implementation reqs***`, not in the functional spec. If the component is a self-contained subsystem or will be reused across modules, promote it to its own module with `create-requires-module` / `refactor-module` instead of a sibling spec.
+The extracted component spec and the rewritten original must together still cover 100% of the original functionality (step 6): the original must **reference** the component, never re-describe it. Keep the component's technology and architecture choices in `***implementation reqs***`, not in the functional spec. If the component is a self-contained subsystem or will be reused across modules, promote it to its own module - one that `requires` it, following `requires-modules.md`, or with `refactor-module` - instead of a sibling spec.
 
 ## Preserving Chronological Order
 

package/genome/skills/refactor-module/SKILL.md

@@ -75,7 +75,7 @@ For each concept, determine where it belongs:
 | Used across multiple modules in the chain | Define in the first module that uses it, and add to that module's `exported_concepts` |
 | Already defined in an import template | Leave in the import — no change needed |
 
-If many concepts are shared across all modules, consider creating a new import module (template) to hold them. This avoids long `exported_concepts` lists and keeps definitions centralized. Use the `create-import-module` skill for this.
+If many concepts are shared across all modules, consider creating a new import module (template) to hold them. This avoids long `exported_concepts` lists and keeps definitions centralized. Write it following `import-modules.md`.
 
 ### 2d. Assign implementation reqs and test reqs
 
@@ -102,7 +102,7 @@ Create the new modules in order, from the base of the chain upward.
 
 ### 3a. Create or update the import template (if needed)
 
-If shared definitions or reqs are being moved to a new import template, create it first using the `create-import-module` skill.
+If shared definitions or reqs are being moved to a new import template, create it first, following `import-modules.md`.
 
 ### 3b. Create the base module
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.13-next.9fe9bb8",
+  "version": "0.1.14-next.3e3ff53",
   "license": "MIT",
   "type": "module",
   "repository": {

package/genome/skills/check-plain-env/SKILL.md

@@ -1,285 +0,0 @@
----
-name: check-plain-env
-description: >-
-  Read a ***plain project — its `.plain` files, `test_scripts/`,
-  and `resources/` — and determine every command-line tool, runtime, package
-  manager, and external service the project needs on the host machine. Probe
-  the host for each one, then emit a `PASS` / `FAIL` report listing what's
-  installed (with versions), what's missing, and concrete OS-specific install
-  commands for the gaps. Run this any time someone is about to render, test,
-  or onboard onto a ***plain project for the first time.
-allowed-tools: [read, bash, ls, grep, find]
----
-
-# Check Plain Env
-
-This skill answers one question: **does the host machine have everything the ***plain project needs to render and test?** It reads the project, derives the requirement list, probes the machine, and returns a report. It never installs anything itself — that decision belongs to the user.
-
-## When to run
-
-- **First time you open a ***plain project on a new machine** — before the first `turri regenerate <module>.plain` or `./test_scripts/run_unittests*.sh` invocation. This is the most common case.
-- **Once a new project's stack is settled** — at the end of `brood`'s stack phase, so the first build does not stop on a missing toolchain.
-- **After `bud`** — when the new feature brought in a new dependency (a new framework, a new service, a new package manager) the project didn't need before.
-- **Before a real render** — alongside `validate`. `validate` answers "do the specs parse?"; this skill answers "can this machine render and test them?". Both should pass.
-- **Onboarding** — when a teammate (or CI runner, or fresh dev container) is about to start using the project.
-- **Debugging a confusing failure** — when a test script exits with "command not found", "module not found", "could not connect", or similar before any test runs.
-- **On demand** — whenever the user asks "what do I need to install for this project?".
-
-This skill is **read-only and observational**. It does not edit `.plain` files or scripts, and it never invokes install commands on the user's behalf.
-
-## What this skill does NOT do
-
-- It does **not** install anything. It only suggests install commands and lets the user run them.
-- It does **not** generate scripts or change project files. Use the `implement-*-testing-script` skills for that.
-- It does **not** start services (databases, brokers, Docker daemons). It only checks whether the right binaries and (optionally) running endpoints are reachable.
-- It does **not** validate the specs themselves (syntax, structure, complexity). Use the `validate` tool for that — the two are complementary.
-- It does **not** print secrets. Check whether an env var is *set* (e.g. `printenv FOO >/dev/null && echo set || echo missing`), never echo its value.
-
-## Workflow
-
-The skill is a **derive → probe → report** pass. It does not stop at the first missing tool; it surfaces every gap so the user gets a single complete shopping list.
-
-### Step 1 — Inventory the project
-
-1. **Detect the host OS** first. Run `uname -s 2>/dev/null || echo "$OS"`. Use the result to (a) pick the right script extensions to inspect (`.sh` vs `.ps1`) and (b) pick the right install commands later (Homebrew, apt, dnf, pacman, choco, scoop, winget).
-2. **List every `.plain` file** in the repo root and in any subdirectory that contains them. Note which are top modules (not `requires`-ed by anything) and which are import modules (under `template/`).
-3. **List every script under `test_scripts/`** (both `.sh` and `.ps1` — projects can ship both).
-4. **List every file under `resources/`** if the directory exists. Schemas and protocol files there often imply running services (e.g. a Postgres `.sql` schema implies a Postgres server).
-5. Print a one-line inventory summary, e.g. `Detected: 2 top modules (backend/api.plain, frontend/web.plain), 4 test_scripts, 3 resources. Host: Darwin.`
-
-### Step 2 — Derive the requirement list (at runtime, from what the project actually says)
-
-The requirement list is **not pre-baked into this skill**. There is no catalog of "things to always check". The list is derived for each project from the project itself, by reading the specs and scripts in front of you and classifying every signal into one of the categories below.
-
-#### What to check vs. what *not* to check
-
-The single most important rule:
-
-> **Check only the layers a package manager cannot install.** Anything `pip install -r requirements.txt`, `npm ci`, `mvn install`, `cargo fetch`, `go mod download`, `bundle install`, `composer install`, etc. would resolve is **out of scope** for this skill. It will be installed by the project's own scripts the moment they run. Checking it here is wasted work and creates false-negative reports the moment the manifest changes.
-
-Concretely:
-
-- ❌ **Do NOT check individual language packages** — not `torch`, not `requests`, not `numpy`, not `FastAPI`, not `express`, not `react`, not a specific JAR in `pom.xml`, not a specific gem in `Gemfile`, not a specific crate in `Cargo.toml`. The language's package manager handles all of it. The same rule applies in every language — Python, Node.js, Java, Go, Rust, Ruby, PHP, .NET, Dart, etc.
-- ✅ **Do check the layers below the package manager**, which fall into four categories. Build the requirement list at runtime by walking through each category and adding only what the project actually needs.
-
-#### Category 1 — Language toolchains and their package managers
-
-For each language the project uses, the *toolchain* must be on the host — the package manager cannot install itself. Decide which toolchains apply by reading the specs and scripts:
-
-- **Signals in `.plain` files**: phrases like `should be in Python`, `should be in Java`, `should be in Go` in `***implementation reqs***`. Find the language; ignore the framework (the framework is a package, not a toolchain).
-- **Signals in `test_scripts/`** (more reliable, because scripts are the executable contract): which interpreter / build tool is invoked at the top level. `python3` / `pip` → Python toolchain. `node` / `npm` / `pnpm` / `yarn` → Node.js toolchain. `mvn` / `gradle` → JDK + Maven/Gradle. `go` → Go toolchain. `cargo` → Rust toolchain. `dotnet` → .NET SDK. `ruby` / `bundle` → Ruby + Bundler. `php` / `composer` → PHP + Composer. `dart` / `flutter` → Dart/Flutter SDK.
-
-For each detected toolchain, probe both the interpreter/compiler **and** its package manager:
-
-- Python → `python3 --version` + `pip --version`.
-- Node.js → `node --version` + `npm --version` (or `pnpm`/`yarn` if the scripts use them).
-- Java → `java -version` + `javac -version` + `mvn -version` (or `gradle --version`).
-- Go → `go version`.
-- Rust → `cargo --version` + `rustc --version`.
-- .NET → `dotnet --version`.
-- Ruby → `ruby --version` + `bundle --version`.
-- PHP → `php --version` + `composer --version`.
-- Flutter / Dart → `flutter --version` + `dart --version`.
-
-**That's where the language-package check stops.** Once `python3` and `pip` are on the host, `pip install -r requirements.txt` will handle `torch`, `numpy`, `requests`, etc. when the test script runs. Don't probe for them here.
-
-#### Category 2 — External services
-
-Services that run as separate processes / daemons and cannot be installed by a language package manager. Identify them at runtime by reading the specs and config:
-
-- **Signals**: a `.plain` file names a service the implementation talks to (database, cache, queue, broker, orchestrator). A `resources/*.sql` schema implies a database. A `docker-compose.yml` (if present) lists services explicitly.
-- For each service found, probe **both** that its CLI is available **and** — when possible — that the service is reachable. "Binary present but service not running" should report as `WARN`, not `FAIL`; the user may want to start it on demand.
-
-No catalog — if the spec says "uses PostgreSQL" you check Postgres, if it says "uses Redis" you check Redis, if it says "uses some-niche-service" you look up its CLI on the fly and probe that. Don't pretend the list is closed.
-
-#### Category 3 — System binaries that language packages wrap
-
-Some language packages are thin wrappers around a system binary that **`pip install` / `npm install` cannot install for you**. The package manager installs the wrapper; the wrapped binary still has to be on the host separately. This is the most commonly missed category.
-
-Decide at runtime by reading the workflow described in the specs. If the workflow can't physically run without an external tool, that tool needs to be checked even though the language wrapper around it is in `requirements.txt`. Examples of the *pattern* (not an exhaustive list — derive yours from the actual project):
-
-- The spec describes OCR → a wrapper like `pytesseract` is in `requirements.txt`, but the host still needs the `tesseract` binary and the language data files.
-- The spec describes video/audio processing → `ffmpeg-python` is in the manifest, but the `ffmpeg` binary itself must be on the host.
-- The spec describes PDF extraction → a Python wrapper is in the manifest, but the `pdftotext` / `pdftoppm` binaries from poppler-utils are still required.
-- The spec describes headless-browser e2e testing → the npm package is in `package.json`, but the actual browser binaries (Chromium, Firefox, WebKit) must be downloaded onto the host separately.
-- The spec describes shelling out to any external CLI from generated code → that CLI must be on the host.
-
-**Heuristic for spotting Category 3:** if removing the package from `requirements.txt` would still leave a binary on the host that the project depends on, the binary belongs in Category 3. If the package *is* the only thing the project needs, it's package-manager territory and out of scope.
-
-Whenever the test scripts themselves invoke a non-language binary (`ffmpeg`, `psql`, `docker`, `tesseract`, ...), that binary is automatically Category 3 — the script is the executable contract. **Always reconcile the spec-derived list against the scripts** before probing.
-
-#### Category 4 — Hardware, drivers, accelerators
-
-Things the OS — not any package manager — must provide. The only category where the chain runs deeper than "is this binary on PATH?".
-
-- **Signals**: a spec mentions GPU acceleration, local model training/fine-tuning, real-time inference, CUDA, MPS / Apple Silicon, hardware-accelerated video encoding, etc.
-- The check is **layered**, and each layer fails independently. Probe each one and surface each result separately, in order, so the user sees exactly where the chain breaks:
-  1. **Driver present?** (e.g. `nvidia-smi` succeeds.)
-  2. **Device visible?** (e.g. `nvidia-smi -L` lists ≥ 1 GPU.)
-  3. **Accelerator SDK installed?** (e.g. `nvcc --version` for the CUDA toolkit.)
-  4. **Acceleration libraries discoverable?** (e.g. cuDNN via `ldconfig -p \| grep libcudnn` on Linux.)
-  5. **The runtime can actually see the accelerator?** (e.g. a one-line Python probe through whatever framework the spec named: `python -c "import torch; print(torch.cuda.is_available(), torch.version.cuda)"`.) This particular layer **does** require the language package, so run it after the test scripts have had a chance to install dependencies — or surface it as "can be verified after `pip install`" if dependencies aren't installed yet.
-  6. **Version compatibility.** If the runtime reports a different CUDA major version than the toolkit, surface a `WARN`. Driver / toolkit / runtime version mismatches are the most common silent GPU bug.
-
-The same shape applies to other accelerators: Apple Silicon / MPS (`uname -m`, `sw_vers`, framework probe), AMD ROCm (`rocminfo`), Intel oneAPI, etc. Look up the relevant probe at runtime from the spec's terminology.
-
-Worked example — the GPU case:
-
-> A `.plain` file declares: `:Implementation: should fine-tune :BaseModel: on the user's local hardware using PyTorch. Training should use available GPUs when present.`
->
-> What the package manager handles (out of scope for this skill): `torch` itself. `pip install -r requirements.txt` will fetch the right wheel.
->
-> What this skill must probe (in scope):
->
-> 1. The **Python toolchain** (Category 1): `python3 --version`, `pip --version`.
-> 2. The **NVIDIA driver** (Category 4, layer 1): `nvidia-smi`.
-> 3. **At least one GPU visible** (Category 4, layer 2): `nvidia-smi -L` lists ≥ 1 device.
-> 4. **CUDA toolkit** (Category 4, layer 3): `nvcc --version`.
-> 5. **cuDNN discoverable** (Category 4, layer 4): `ldconfig -p \| grep libcudnn` on Linux; skip on macOS.
-> 6. **PyTorch actually sees the GPU** (Category 4, layer 5): `python -c "import torch; print(torch.cuda.is_available(), torch.version.cuda)"` — noting this requires `torch` to be installed (i.e. requires the test scripts to have run their install step at least once).
-> 7. **Version match** (Category 4, layer 6): cross-check `torch.version.cuda` against `nvcc --version`. Mismatch → `WARN`.
->
-> The skill never asks "is `torch` installed?". That belongs to `pip`.
-
-#### Category 5 — Always required
-
-Add these to every requirement list regardless of project:
-
-- turri's own needs — Node, bash, the OS sandbox, a model provider — are checked by `turri doctor`. Run it and report its result; do not probe those separately.
-- A shell matching the testing scripts' extension (Bash for `.sh`, PowerShell for `.ps1`).
-- `git` (the renderer uses it; almost every plain project tracks itself in git).
-
-### Step 3 — Probe the host
-
-For every requirement the project produced in Step 2, run a check using the `bash` tool. Capture stdout/stderr and exit code. Classify each result:
-
-- **PASS** — present and (where a version was specified) at or above the required version.
-- **WARN** — present but at a version that doesn't match what the project explicitly asks for (e.g. spec says Java 17, host has Java 21), or service binary present but the service itself isn't running, or a Category 4 sub-layer is mismatched against another (e.g. CUDA toolkit version doesn't match what the framework expects).
-- **FAIL** — missing, unreachable, or below the minimum version.
-
-Probe in the same category order Step 2 produced them, so the report reads top-down:
-
-1. **Category 1 — Language toolchains.** Run the toolchain + package-manager probes listed in Step 2's Category 1 for the languages this project actually uses. Do not probe individual language packages.
-2. **Category 5 — turri and `git`.** Always required, independent of the project. `turri doctor`, `git --version`. Verify the shell flavor matches the scripts' extension; a `.sh`-only project on native Windows is a `FAIL` (suggest WSL).
-3. **Category 2 — External services.** For each service identified at runtime, probe the CLI's presence first, then — if the CLI exists — check whether the service itself is reachable. Service binary present but daemon down → `WARN`, not `FAIL`.
-4. **Category 3 — System binaries that language packages wrap.** For each one identified in Step 2, check the system binary is on `PATH` (`which <bin>` / `<bin> --version`). The wrapper package itself isn't probed.
-5. **Category 4 — Hardware, drivers, accelerators.** Walk the layered probe from Step 2 in order (driver → device visibility → SDK → acceleration libs → framework-sees-it → version match), reporting each layer's result separately. Never collapse a multi-layer failure into a single "GPU not available" message — each layer has a different fix.
-6. **Credentials and config holes.** For every env var, dotfile, or cloud CLI login state the project implies, probe its presence without printing its value: `printenv VAR >/dev/null && echo set || echo missing`, `[ -f <path> ] && echo present || echo missing`, `aws sts get-caller-identity` / `gcloud auth list` / `az account show` for cloud SDKs.
-
-### Step 4 — Report
-
-Emit a single report with **the verdict on the first line** so callers can pattern-match without parsing the body:
-
-- **`PASS`** — every required item is present at an acceptable version. Follow with a one-paragraph summary listing what was checked.
-- **`WARN`** — everything required is present but at least one item triggered a soft warning (version mismatch, service not currently running). Follow with the numbered list of warnings.
-- **`FAIL`** — at least one required item is missing or below minimum version. Follow with a numbered list of every gap.
-
-For every **FAIL** and **WARN** item, the report must include four columns:
-
-| Column | Content |
-|---|---|
-| **What** | The missing tool/service/credential. |
-| **Why** | Which spec, script, or library introduced this requirement (e.g. "`backend/api.plain` says `using FastAPI`", "`test_scripts/run_unittests_python.sh` calls `pytest`"). |
-| **Status** | "missing", "outdated (found X, need Y)", "binary present but service not running", or "env var not set". |
-| **How to install** | OS-specific command(s). See [Install suggestions](#install-suggestions) below. |
-
-Group the report into the same six probe groups used in Step 3 (toolchains, turri/git, services, system binaries, hardware, credentials), so the user can fix one whole layer at a time.
-
-End the report with a one-liner reminder: `Re-run check-plain-env after installing missing items to confirm.`
-
-## Install suggestions
-
-When emitting an install command, **match the host OS** detected in Step 1. Prefer the OS's first-party package manager. Don't suggest `curl | sh` style installs unless there is no alternative.
-
-The tables below are a **starter set** of well-known install commands for the things projects most often need. They are **not** a list of "things to check" — that list is derived per project in Step 2. When the requirement list contains something not in these tables (e.g. a niche service, a specialty CLI), look up the canonical install command for the detected OS at the time of report generation rather than skipping the row or inventing a command.
-
-### macOS (Darwin)
-
-| Requirement | Suggested install |
-|---|---|
-| Python 3 | `brew install python@3.12` |
-| Node.js | `brew install node` (or `brew install nvm` for multi-version) |
-| Go | `brew install go` |
-| Rust | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` (no Homebrew equivalent that stays current) |
-| Java | `brew install openjdk@21` then follow the post-install `sudo ln -sfn ...` step |
-| Maven | `brew install maven` |
-| Gradle | `brew install gradle` |
-| PostgreSQL | `brew install postgresql@16` then `brew services start postgresql@16` |
-| MySQL | `brew install mysql` then `brew services start mysql` |
-| Redis | `brew install redis` then `brew services start redis` |
-| Docker | Install Docker Desktop from https://docker.com/products/docker-desktop |
-| `pg_config` (psycopg) | comes with `brew install postgresql@16` |
-| Xcode CLT | `xcode-select --install` |
-| `turri` | follow the install instructions at https://turri.ai |
-
-### Linux (Debian/Ubuntu)
-
-| Requirement | Suggested install |
-|---|---|
-| Python 3 | `sudo apt update && sudo apt install -y python3 python3-pip python3-venv` |
-| Node.js | `curl -fsSL https://deb.nodesource.com/setup_20.x \| sudo -E bash - && sudo apt install -y nodejs` |
-| Go | `sudo apt install -y golang-go` (or download from https://go.dev/dl/ for the latest) |
-| Rust | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` |
-| Java | `sudo apt install -y openjdk-21-jdk` |
-| Maven | `sudo apt install -y maven` |
-| PostgreSQL | `sudo apt install -y postgresql postgresql-contrib && sudo systemctl start postgresql` |
-| Redis | `sudo apt install -y redis-server && sudo systemctl start redis-server` |
-| Docker | follow https://docs.docker.com/engine/install/ubuntu/ |
-| `pg_config` (psycopg) | `sudo apt install -y libpq-dev` |
-| C/C++ build tools | `sudo apt install -y build-essential` |
-
-### Linux (Fedora/RHEL)
-
-Equivalent commands with `sudo dnf install -y ...` instead of `apt`. Surface them when the host is detected as Fedora/RHEL (e.g. presence of `/etc/redhat-release` or `dnf --version` succeeding).
-
-### Windows (native PowerShell)
-
-| Requirement | Suggested install |
-|---|---|
-| Python 3 | `winget install Python.Python.3.12` or `choco install python` |
-| Node.js | `winget install OpenJS.NodeJS.LTS` or `choco install nodejs-lts` |
-| Go | `winget install GoLang.Go` |
-| Rust | `winget install Rustlang.Rustup` |
-| Java | `winget install Microsoft.OpenJDK.21` |
-| PostgreSQL | `winget install PostgreSQL.PostgreSQL` |
-| Docker | `winget install Docker.DockerDesktop` |
-| MSVC build tools | `winget install Microsoft.VisualStudio.2022.BuildTools` |
-
-If the project's `test_scripts/` are `.sh` only and the host is native Windows, suggest **WSL** (`wsl --install`) rather than trying to make Bash scripts run under PowerShell.
-
-### When you can't pick
-
-When the host OS detection in Step 1 was inconclusive (e.g. an unrecognized Linux distro), include the macOS and Debian/Ubuntu commands and tell the user to adapt for their package manager. Never invent install commands for a distro you can't identify.
-
-## Anti-patterns
-
-- **(Hard mistake) Don't probe individual language packages.** Anything `pip install -r requirements.txt`, `npm ci`, `mvn install`, `cargo fetch`, `go mod download`, `bundle install`, `composer install`, etc. would resolve is out of scope. `torch`, `requests`, `numpy`, `FastAPI`, `express`, `react`, JARs, gems, crates — all package-manager territory. Check the toolchain (`python3`, `pip`, `node`, `npm`, `mvn`, `cargo`, ...) and stop there. Probing the package itself creates false negatives the moment `requirements.txt` changes and duplicates work the test scripts will do anyway.
-- **Don't stop after the directly named technologies.** A spec that says "fine-tune on local hardware using PyTorch" never says "CUDA", but the workflow can't run without CUDA. Always work through Category 3 (system binaries that language packages wrap) and Category 4 (hardware/drivers) — not only the directly named runtimes. These categories are where the workflow's hidden requirements live.
-- **Don't merge a chain of failures into one generic message.** "GPU not available" is not a useful report. The chain is `driver → device visibility → toolkit → acceleration libs → framework-sees-it → version match`; each layer has a different fix. Surface each layer separately.
-- **Don't work only from `.plain` files.** Always cross-reference with `test_scripts/` — the scripts are the executable contract. If a script invokes a non-language binary the specs never mention, that binary is automatically a Category 3 requirement.
-- **Don't pre-bake a catalog.** Derive the requirement list at runtime from the project in front of you. A hard-coded "things to always check" table becomes wrong the moment any project deviates from the assumed shape — and every project does.
-- **Don't probe testing framework binaries as if they were independent.** `pytest`, `jest`, `vitest`, `phpunit`, `junit-console`, etc. are installed by the package manager via `requirements.txt` / `package.json` / `pom.xml`. The toolchain check (Category 1) is enough — the framework binary itself is out of scope.
-- **Don't probe in silence.** Use the `bash` tool and capture the actual command output (version strings, exit codes). Telling the user "looks like Python is installed" without running `python3 --version` is guessing.
-- **Don't print secret values.** Check whether `DATABASE_URL`, provider API keys, etc. are set, not what they contain. Use `printenv VAR >/dev/null` not `printenv VAR`.
-- **Don't install anything on the user's behalf.** Even when the install command is obvious. The user needs to opt in.
-- **Don't stop at the first FAIL.** Run the full sweep so the report is complete in one pass.
-- **Don't suggest `curl | sh` installs when a package manager works.** Reserve the upstream installer fallback for cases where no package-manager option exists (e.g. `rustup`, sometimes Go).
-- **Don't ignore version mismatches.** If a spec says Java 17 and the host has Java 21, surface that as a `WARN` so the user can decide — don't silently let it pass.
-- **Don't duplicate this check inline elsewhere.** Other skills (`brood`, `bud`) that need an env check should **delegate to `check-plain-env`** rather than re-implementing the probe themselves. This skill is the single source of truth.
-
-## Validation Checklist
-
-- [ ] Host OS detected (`uname -s` / `$OS`) before any other action.
-- [ ] Requirement list derived **at runtime from this project's** `.plain` files, `test_scripts/`, and `resources/` — no pre-baked catalog used.
-- [ ] **No individual language packages probed.** Only the toolchain + package manager for each detected language.
-- [ ] Every script under `test_scripts/` opened and read; every non-language binary it invokes added to the Category 3 list.
-- [ ] Every external service named in the specs is in the Category 2 list, with both a binary probe and (when feasible) a reachability probe.
-- [ ] Every hardware / accelerator signal ("GPU", "fine-tune", "local inference", "CUDA", "MPS", etc.) triggered the layered Category 4 probe.
-- [ ] Every requirement probed via the `bash` tool with an actual version / availability command (no "looks installed" guesses).
-- [ ] GPU / accelerator chains probed layer-by-layer (driver → device visibility → toolkit → acceleration libs → framework-sees-it → version match), with each layer reported separately.
-- [ ] Each result classified as PASS / WARN / FAIL.
-- [ ] Report has the verdict on the first line.
-- [ ] Every FAIL and WARN row has all four columns: What / Why / Status / How to install.
-- [ ] Install suggestions match the detected host OS (no Debian commands on macOS, no `brew` on Linux, etc.).
-- [ ] No secret values were printed at any point.
-- [ ] Nothing was installed; no project files were modified.

package/genome/skills/create-import-module/SKILL.md

@@ -1,104 +0,0 @@
----
-name: create-import-module
-description: >-
-  Create a ***plain import module that provides shared definitions,
-  implementation reqs, and test reqs for other modules to import. Use when
-  the user wants to create a new .plain file that contains only definitions,
-  implementation reqs, and/or test reqs — no functional specs.
-allowed-tools: [read, write, edit, bash, ls, grep, find]
----
-
-# Create Import Module
-
-## What an Import Module Is
-
-An import module is a `.plain` file that lives in the **`template/`** directory and contains **only** `***definitions***`, `***implementation reqs***`, and/or `***test reqs***`. It must **not** contain `***functional specs***` and must **not** use `requires` in its frontmatter. Other modules pull in its content via the `import` field in their YAML frontmatter, gaining access to its definitions and reqs.
-
-Use import modules for:
-- Sharing concept definitions across multiple modules
-- Providing common implementation requirements (e.g., technology stack, coding standards)
-- Providing common test requirements
-- Creating reusable foundational structure (templates)
-
-If the module needs functional specs (i.e., it describes what software should do), it is not an import module — see the `create-requires-module` skill.
-
-## Workflow
-
-1. **Determine what shared content this module should provide** — which definitions, implementation reqs, or test reqs will other modules need?
-2. **Create the `.plain` file in the `template/` directory** with YAML frontmatter. Use `required_concepts` to declare concepts that importing modules must define. It may optionally `import` other templates for layered reuse, but must **not** use `requires`.
-3. **Add the shared content** — definitions, implementation reqs, and/or test reqs.
-4. **Do not add `***functional specs***`** — import modules must not contain functional specs.
-5. **Verify concept availability** — ensure all `:Concepts:` referenced are either defined in this module, provided by its own imports, declared as `required_concepts`, or are predefined concepts.
-
-## Format
-
-The `import` field is a list of module paths in the YAML frontmatter:
-
-```plain
----
-import:
-  - base_template
-required_concepts: [":AppName:"]
-description: Shared API definitions and reqs
----
-
-***definitions***
-
-- :ApiClient: is the HTTP client used to communicate with external services.
-
-- :ApiResponse: is the response returned by :ApiClient:.
-
-***implementation reqs***
-
-- :Implementation: should handle HTTP errors by raising appropriate exceptions.
-
-- :ApiClient: should support configurable timeouts.
-
-***test reqs***
-
-- :ConformanceTests: should mock all external HTTP calls made by :ApiClient:.
-```
-
-The default import directory is `template/` — the `template/` prefix is not needed in import paths. The `.plain` extension is omitted. Note the absence of `***functional specs***` — import modules must not have them.
-
-## Satisfying Required Concepts
-
-If an imported template declares `required_concepts`, the importing module **must** define those concepts in its own `***definitions***` section:
-
-```plain
----
-import:
-  - auth_template
----
-
-> auth_template declares required_concepts: [":AuthSchema:", ":AuthApiSpec:"]
-> So this module must define them:
-
-***definitions***
-
-- :AuthSchema: is the JSON schema describing the authentication data structure.
-
-- :AuthApiSpec: is the OpenAPI specification for the external service's auth endpoint.
-```
-
-## Import vs Requires
-
-| Aspect | `import` | `requires` |
-|--------|----------|------------|
-| Pulls in definitions | Yes | No (only `exported_concepts`) |
-| Pulls in implementation reqs | Yes | No |
-| Pulls in test reqs | Yes | No |
-| Pulls in functional specs | No | Yes (as previous requirements, transitively) |
-| Copies generated code | No | Yes (accumulated ancestor chain) |
-| Typical use | Templates, shared definitions | Attaching a module to the build chain |
-
-## Validation Checklist
-
-- [ ] Module file is in the `template/` directory
-- [ ] Module does **not** contain `***functional specs***`
-- [ ] Module does **not** use `requires` in its frontmatter
-- [ ] Contains at least one of: definitions, implementation reqs, or test reqs
-- [ ] All `required_concepts` from any imports this module itself uses are satisfied
-- [ ] `required_concepts` declared for any concepts referenced but not defined here
-- [ ] No concept name collisions between this module's imports and local definitions
-- [ ] YAML frontmatter is correctly formatted between `---` markers

package/genome/skills/create-requires-module/SKILL.md

@@ -1,109 +0,0 @@
----
-name: create-requires-module
-description: >-
-  Create a ***plain module that uses requires to depend on another module in
-  the build chain. Use when the user wants to create a new .plain file that
-  builds on top of a previously built module, inheriting its functional specs
-  and generated code as a starting point.
-allowed-tools: [read, write, edit, bash, ls, grep, find]
----
-
-# Create Requires Module
-
-## What Requires Does
-
-`requires` attaches the current module to the project's build chain. The required module is built **before** the current one, and its generated code — the accumulated output of that module and all its ancestors — is copied as the starting point. The current module does not need to functionally extend the required module, but their outputs are never independent: the current module's code physically contains the required module's.
-
-When this module is rendered:
-- The required module's generated code (`plain_modules/<required_module>/code`) is copied as the starting point.
-- The `***functional specs***` of the required module **and all its ancestors** become visible as **previous functional specs**.
-- Of the required module's definitions, only the concepts in its `exported_concepts` are visible, each with its full definition text. Export visibility is **not** transitive — to see an ancestor's exports, list that ancestor in `requires` too.
-
-All modules connected by `requires` form a single tree with a common root. **Diamond joins are prohibited**: multiple `requires` entries must lie on one root-to-tip ancestor path. The deepest entry is the attachment point; the other entries exist only to make those ancestors' exports visible.
-
-Use `requires` for:
-- Building on top of an existing module's functionality
-- Attaching a module at the right point in the build chain, even when it addresses a different concern
-
-If you only need shared definitions and reqs (no functional specs, no generated code), use `import` instead — see the `create-import-module` skill.
-
-## Workflow
-
-1. **Identify the attachment point.** Determine which existing module this new module attaches after in the build chain. That module must already exist and be renderable. If listing additional modules, verify each is an ancestor of the attachment point — no diamond joins.
-2. **Create the `.plain` file at the repository root** with YAML frontmatter containing the `requires` field. Modules with functional specs live at the root, not in `template/`.
-3. **Review the functional specs of the whole ancestor chain** — they will be treated as previous requirements. Your new functional specs must not conflict with any of them.
-4. **Review each listed module's `exported_concepts`** — only those concepts are available to reference; an ancestor's exports require listing that ancestor.
-5. **Add module-specific content** — definitions, implementation reqs, test reqs, and functional specs unique to this module.
-6. **Check for conflicts** between your new functional specs and any spec in the ancestor chain.
-
-## Format
-
-The `requires` field is a list of module paths in the YAML frontmatter:
-
-```plain
----
-requires:
-  - base_module
-import:
-  - shared_template
-description: Extended module that builds on base_module
----
-
-***definitions***
-
-- :NewFeature: is a feature added by this module.
-
-***functional specs***
-
-- :NewFeature: is available.
-```
-
-A module can use both `requires` and `import` together. `requires` points to other root-level modules; `import` resolves from the default `template/` directory (no prefix needed).
-
-Multiple `requires` entries are legal only when they lie on one ancestor path (e.g., `requires: [auth, messaging]` where `messaging` itself requires `auth`). The deepest entry (`messaging`) is the attachment point; `auth` is listed only to make its exports visible.
-
-## Exported Concepts
-
-The required module controls what concepts are visible via `exported_concepts`:
-
-```plain
-> In the required module's frontmatter:
----
-exported_concepts: [":StorageClient:", ":BackupResult:"]
----
-```
-
-Only `:StorageClient:` and `:BackupResult:` would be available to modules that `require` this one, each with its full definition text. All other concepts from the required module are internal.
-
-## Chronological Ordering with Requires
-
-Functional specs from the whole `requires` ancestor chain are considered **previous functional specs**. This means:
-- They are already rendered and their code exists.
-- Your new specs are rendered after them, with full awareness of what they defined.
-- Your new specs must not conflict with any spec in the ancestor chain.
-- The renderer sees the chain's functional specs as context when rendering yours.
-
-The current module may or may not be functionally related to the required module — `requires` places it at the right point in the accumulating build chain either way.
-
-## Import vs Requires
-
-| Aspect | `import` | `requires` |
-|--------|----------|------------|
-| Pulls in definitions | Yes | No (only `exported_concepts`) |
-| Pulls in implementation reqs | Yes | No |
-| Pulls in test reqs | Yes | No |
-| Pulls in functional specs | No | Yes (as previous requirements, transitively) |
-| Copies generated code | No | Yes (accumulated ancestor chain) |
-| Typical use | Templates, shared definitions | Attaching a module to the build chain |
-
-## Validation Checklist
-
-- [ ] Module file is at the repository root (not in `template/`)
-- [ ] Required module exists and is renderable
-- [ ] All `requires` entries lie on one ancestor path — no diamond joins
-- [ ] The deepest `requires` entry is the intended attachment point
-- [ ] Every listed module's `exported_concepts` provide the concepts you need
-- [ ] New functional specs do not conflict with any spec in the ancestor chain
-- [ ] Module has at least one functional spec and one implementation req
-- [ ] Both `requires` and `import` are used correctly (not mixed up)
-- [ ] YAML frontmatter is correctly formatted between `---` markers