genesis-compiler 1.1.0 → 1.2.0

package/README.md

@@ -120,7 +120,9 @@ Hosts that create dependency-empty workspaces can call the public
 `inspectWorkspaceSetup()` API. A concrete Stack piece may declare one exact,
 ordered `## Workspace setup` recipe with labels, argument arrays expressed as
 backticked tokens, abstract runtimes, and optional project-relative working
-directories. The built-in `jskit` piece declares `npm install`; generic
+directories and readiness paths. A recipe whose declared project marker does
+not exist remains unconfigured until a later inspection. The built-in `jskit`
+piece waits for `package.json` and then declares `npm install`; generic
 `nodejs` and `php` deliberately declare no installer. One project section in
 `genesis/stack.md` replaces all component defaults, including with
 `- Nothing.`. Without that override, exactly one component recipe is used;
@@ -128,6 +130,14 @@ multiple component recipes are reported as ambiguous and never merged.
 Genesis does not run the recipe. Stack resources such as database variables do
 not gate dependency installation.
 
+Hosts that manage project environments can call `inspectEnvironment()`.
+An optional readable `## Environment files` section declares safe
+project-relative dotenv projections such as `.env`. A project declaration
+replaces component defaults, including with `- Nothing.`; otherwise component
+paths compose. Genesis reports resource declarations, value-free missing-input
+diagnostics, and paths. It never returns values, writes files, stores secrets,
+or decides which resolved values a host should materialize.
+
 Hosts that provide previews can call the public `inspectLaunch()` API. An
 optional readable `## Launch` section in `genesis/stack.md` declares labeled
 targets, exact backticked argument tokens, relative working directories,
@@ -247,6 +257,7 @@ genesis prompt "Add filtering by note title"
 
 ```bash
 genesis prompt                                      # implementation work
+genesis prompt --task start                        # open a new or existing project conversation
 genesis prompt "Add filtering by note title"
 genesis prompt --task deslop                        # explicit cleanup
 genesis prompt --task deslop "Only review billing"
@@ -256,8 +267,12 @@ genesis prompt --task describe                      # create/refresh Blueprint a
 genesis prompt --task review                        # compare intent, code, and explanation
 ```
 
-The six task types are deliberately explicit:
+The seven task types are deliberately explicit:
 
+- `start` opens the project conversation. For a new project it asks what the
+  app is about, presents relevant choices from the live Stack catalog, and
+  waits for the person to select technology. For an existing project it asks
+  what the person wants to understand or change.
 - `work` implements the Blueprint and optional request using current code,
   Program, selected Stack context, and progressively loaded Agent Skills.
 - `deslop` requests cleanup explicitly. Codex projects also receive a bounded
@@ -375,6 +390,7 @@ import {
   getContext,
   indexCodebase,
   initialize,
+  inspectEnvironment,
   inspectLaunch,
   inspectWorkspaceSetup,
   installCodex,
@@ -394,7 +410,11 @@ detailed Machine City and simple Program City projections.
 `inspectWorkspaceSetup()` returns one normalized, shell-free workspace
 preparation recipe—or an explicit unconfigured or ambiguous result—for a host
 to execute with its own pinned runtimes, caches, process isolation, and
-credentials.
+credentials. A configured recipe may remain unconfigured while it waits for a
+technology-declared project marker.
+`inspectEnvironment()` returns normalized Stack resource declarations,
+value-free missing-input diagnostics, and dotenv projection paths without
+returning any environment value.
 `inspectLaunch()` returns a validated, normalized Stack launch declaration for
 a host to execute with its own runtime, port, process, readiness, preview
 identity, secret, and browser policy.

package/docs/prompt-integration.md

@@ -15,7 +15,13 @@ const work = await generatePrompt({
 await currentAgent.send(work.prompt);
 ```
 
-Tasks are `work`, `deslop`, `program`, `blueprint`, `describe`, and `review`.
+Tasks are `start`, `work`, `deslop`, `program`, `blueprint`, `describe`, and `review`.
+`start` is the host-independent first conversation: it classifies an initialized
+project from current Genesis facts, asks what a new app is about, exposes the
+live Stack catalog for an explicit user choice, or asks what the person wants
+to do with an existing project. For an existing uninitialized codebase it owns
+the adoption recommendation as part of the same portable prompt. A host such as Vibe64 sends this prompt on the
+first chat turn; it does not recreate the questions or Stack catalog.
 `describe` creates or refreshes the complete Blueprint and useful Program in one
 agent task. The host owns the agent and its interaction. Genesis owns only
 transparent prompt construction and deterministic project operations.

package/docs/stack-components.md

@@ -43,6 +43,10 @@ What this component contributes.
 - Concise supplemental guidance used during implementation, explanation,
   review, and cleanup.
 
+## Environment files
+
+- Dotenv `.env`
+
 ## Workspace setup
 
 - Prepare `Install dependencies` with `example-runtime`: `example-install` `--locked`
@@ -99,13 +103,17 @@ through `genesis verify`.
 fresh workspace. Each entry uses this readable, shell-free form:
 
 ```markdown
-- Prepare `label` with `runtime` `another-runtime` in `optional/workdir`: `command` `argument`
+- Prepare `label` with `runtime` `another-runtime` in `optional/workdir` when `optional/marker` exists: `command` `argument`
 ```
 
 Every command and argument is a separate backticked value and is returned as
 an `argv` array. Runtime names are opaque technology ids. Omitted `in` means
 the project root; otherwise the working directory must be canonical and
-project-relative. `- Nothing.` is valid only as the entire section and lets a
+project-relative. The optional `when` path is also canonical and
+project-relative. Until it exists, inspection reports the recipe as
+`unconfigured`; this lets a host safely re-inspect after an agent creates a
+technology substrate without knowing that technology's filenames. `- Nothing.`
+is valid only as the entire section and lets a
 project explicitly disable component setup. Genesis validates and reports the
 recipe but never chooses a runtime, runs a command, installs a dependency, or
 infers a package manager. Generic language pieces such as `nodejs` and `php`
@@ -123,6 +131,15 @@ Precedence is intentionally small and deterministic:
 General Stack resources do not gate Workspace setup. In particular, missing
 database variables do not prevent an otherwise independent dependency install.
 
+`Environment files` optionally declares project-relative dotenv projections a
+host may materialize from its own resolved project environment. Genesis
+validates and returns only the format and path; it never reads environment
+values, writes a file, stores a secret, or chooses which variables belong in a
+projection. A project `## Environment files` section in `genesis/stack.md`
+replaces component declarations, including with `- Nothing.`. Without a
+project section, component declarations compose and identical paths collapse.
+The declaration is useful independently of Launch and Workspace setup.
+
 `Launch` is an optional readable declarative recipe for hosts that need to
 offer a preview without guessing how a concrete technology starts. Repeat a
 ``### Target `id`: label`` block to declare several targets. Default, Workdir,
@@ -211,25 +228,40 @@ Replacement component description.
 
 Each field is optional. `Override` replaces only that installed field; `Add`
 then follows the installed or overridden value. These files cannot alter
-dependencies, conflicts, Agent Skill source, indexers, resources, commands,
-Workspace setup, or Launch declarations.
+dependencies, conflicts, Agent Skill source, indexers, resources, environment
+files, commands, Workspace setup, or Launch declarations.
 `genesis stack add` preserves the files and composes their effective prose after
 dependency resolution.
 
 A project may select component ids in `genesis/stack.md`, replace component
-Workspace setup defaults with one project recipe, replace component Verify
-defaults with its own `## Commands`, and replace every component Launch target
-with one project `## Launch` contract. With no project Launch section, selected
-component targets compose; duplicate ids or multiple defaults are rejected
-rather than guessed. `genesis stack add` preserves existing project Workspace
-setup and Launch sections. Adding another language, framework, database, or
-integration is therefore an isolated Stack/indexer contribution rather than a
-prompt or controller special case.
+environment-file declarations, replace component Workspace setup defaults
+with one project recipe, replace component Verify defaults with its own
+`## Commands`, and replace every component Launch target with one project
+`## Launch` contract. With no project Launch section, selected component
+targets compose; duplicate ids or multiple defaults are rejected rather than
+guessed. `genesis stack add` preserves existing project Environment files,
+Workspace setup, and Launch sections. Adding another language, framework,
+database, or integration is therefore an isolated Stack/indexer contribution
+rather than a prompt or controller special case.
 
 Description, Guidance, Agent Skill, and Deslop prose are instructions, not
 verification evidence. Changes to them do not stale an exact successful
-verification record; selected component ids, resources, Workspace setup,
-launch targets, and verification commands remain part of the Stack identity.
+verification record; selected component ids, resources, environment files,
+Workspace setup, launch targets, and verification commands remain part of the
+Stack identity.
+
+Hosts inspect normalized environment requirements independently:
+
+```js
+import { inspectEnvironment } from 'genesis-compiler';
+
+const projectEnvironment = await inspectEnvironment({ environment, projectRoot });
+```
+
+The result has `status` (`ready`, `missing-inputs`, or `unconfigured`),
+`stackHash`, selected `components`, declared `resources`, value-free
+`diagnostics`, and normalized `files`. Each file contains `format`, `path`, and
+`source`. Environment values never cross this API boundary.
 
 Fresh-workspace hosts read setup from the package root:
 
@@ -242,8 +274,11 @@ const setup = await inspectWorkspaceSetup({ projectRoot, environment });
 The setup result has `status` (`ready`, `blocked`, or `unconfigured`),
 `stackHash`, an exact ready-recipe `recipeHash`, selected `components`, its `source`, distinct
 `runtimeRequirements`, normalized ordered `steps`, and `diagnostics`. Each step
-contains `label`, `argv`, `runtimeRequirements`, and `workdir`. `blocked` means
-component recipes conflict, not that an unrelated Stack resource is absent.
+contains `label`, `argv`, `runtimeRequirements`, `workdir`, and an optional
+`readyWhen` project path. `blocked` means component recipes conflict, not that
+an unrelated Stack resource is absent. An absent `readyWhen` marker produces
+the unconfigured diagnostic `STACK_WORKSPACE_SETUP_WAITING`, never a failed or
+blocked result.
 The optional environment object is accepted for a consistent host inspection
 boundary, but Workspace setup v1 neither reads nor returns its values.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with optional Codex hooks.",
   "repository": {
@@ -33,6 +33,7 @@
     "prompts/program.txt",
     "prompts/reconcile.txt",
     "prompts/review.txt",
+    "prompts/start.txt",
     "prompts/work.txt",
     "plugins/genesis",
     "skills",

package/plugins/genesis/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Makes Codex aware of optional Genesis adoption for existing projects.",
   "author": {
     "name": "Mobily Enterprises"

package/prompts/start.txt

@@ -0,0 +1,30 @@
+Read and follow `.agents/skills/genesis-project/SKILL.md` completely.
+
+This is the project-opening conversation. Do not begin implementation until
+the product direction and any technology choice needed for the first useful
+step are clear.
+
+When `projectKind` is `new`, first ask what the app is about. Ask up to three
+concise, high-impact questions at a time. Use `availableStackPieces` to present
+only the relevant choices, explain them in product language, and let the user
+decide. Never silently select a technology. After an explicit choice, use
+`genesis stack add <piece...>`; do not edit `genesis/stack.md` by hand. Establish
+the non-technical Blueprint from the user's answers before implementation.
+If the product direction becomes clear while Stack is still empty, do not end
+the turn after only writing or summarizing the Blueprint: present the relevant
+Stack choices in that same turn and ask the user to select one explicitly.
+
+When `projectKind` is `existing`, ask what the user wants to understand or
+change. Use the current Blueprint, Stack, Program, and code index when present.
+If the existing implementation is not yet explained, recommend the Genesis
+description/adoption path instead of pretending its intent is known.
+
+When `projectKind` is `existing-uninitialized`, ask what the user wants to
+understand or change and strongly recommend `genesis adopt` before substantial
+work. Explain that adoption preserves the implementation and prepares the
+Blueprint and Program prompt. Do not run it without the user's approval. If the
+user declines, continue normally and do not repeat the recommendation.
+
+If the request already contains an unambiguous product description and an
+explicit Stack choice, you may apply that choice and establish the Blueprint.
+Otherwise this is a conversational turn: ask, listen, and preserve the source.

package/prompts/work.txt

@@ -19,3 +19,10 @@ constructing a parallel fallback.
 
 Run focused checks when useful. Summarize files changed, checks actually run,
 and anything still requiring attention.
+
+If no Stack components are selected, continue the project-opening
+conversation instead of guessing a technology. Use `genesis stack list` for
+the current catalog, present relevant choices, wait for an explicit decision,
+and add the selection with `genesis stack add <piece...>` before relying on
+technology-specific setup or launch behavior. Do not end after only updating
+or summarizing the Blueprint while the Stack remains empty.

package/src/cli.js

@@ -31,7 +31,7 @@ const USAGE = `Usage:
   genesis context <path...>
   genesis index [function-or-path...]
   genesis prompt [request...]
-  genesis prompt --task <work|deslop|program|blueprint|describe|review> [request...]
+  genesis prompt --task <start|work|deslop|program|blueprint|describe|review> [request...]
   genesis verify
   genesis check
 

package/src/index/assets.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 
 const root = new URL('../../', import.meta.url);
 const assets = {
+  start: new URL('prompts/start.txt', root),
   work: new URL('prompts/work.txt', root),
   describe: new URL('prompts/describe.txt', root),
   reconcile: new URL('prompts/reconcile.txt', root),

package/src/index/environment-files.js

@@ -0,0 +1,19 @@
+import { gitContext } from './git.js';
+import { readStack } from './stack.js';
+import { missingStackResources } from './stack-preflight.js';
+
+/** Inspect Stack environment requirements without returning or writing values. */
+export async function inspectProjectEnvironment({ environment = process.env, projectRoot } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const stack = await readStack(root);
+  const diagnostics = missingStackResources({ environment, resources: stack.resources });
+  const configured = stack.environmentFiles.length > 0 || stack.resources.length > 0;
+  return {
+    status: !configured ? 'unconfigured' : diagnostics.length > 0 ? 'missing-inputs' : 'ready',
+    stackHash: stack.identityHash,
+    components: stack.components.map(({ id }) => id),
+    files: stack.environmentFiles,
+    resources: stack.resources,
+    diagnostics,
+  };
+}

package/src/index/process.js

@@ -1,10 +1,21 @@
 import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
 
 import { GenesisError } from './errors.js';
 
 const MAX_DIAGNOSTIC_OUTPUT = 16_384;
-const executeFile = promisify(execFile);
+
+function executeFile(command, args, options) {
+  return new Promise((resolve, reject) => {
+    const child = execFile(command, args, options, (error, stdout, stderr) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+    child.stdin?.end();
+  });
+}
 
 function boundedDiagnosticOutput(buffer) {
   const source = buffer.toString('utf8');

package/src/index/prompt.js

@@ -3,15 +3,19 @@ import { inspectProjectSkills, renderAgentSkillCatalog } from './agent-skills.js
 import { buildProjectIndex, MACHINE_CITY_PATH, PROGRAM_CITY_PATH } from './code-index.js';
 import { BLUEPRINT_SKELETON_SOURCE, readBlueprint } from './blueprint.js';
 import { readStack, stackPromptContext } from './stack.js';
+import { listBuiltinStackPieces } from './stack-catalog.js';
 import { GenesisError } from './errors.js';
 import { gitContext } from './git.js';
 import { inspectProgram } from './program.js';
 import { inspectVerification } from './project-state.js';
 import { missingStackResources } from './stack-preflight.js';
 import { stableJson } from './utils.js';
+import { gitVisibleFileStates } from './project-files.js';
+import { isProjectContentPath } from './paths.js';
 
-const TASKS = new Set(['work', 'deslop', 'program', 'blueprint', 'describe', 'review']);
+const TASKS = new Set(['start', 'work', 'deslop', 'program', 'blueprint', 'describe', 'review']);
 const DEFAULT_REQUEST = {
+  start: 'Start a conversation about this project.',
   work: 'Implement the product intent expressed by the current Blueprint.',
   deslop: 'Simplify the current Git-visible work without making unrelated changes.',
   program: 'Refresh the complete useful Program for the code that exists now.',
@@ -19,6 +23,15 @@ const DEFAULT_REQUEST = {
   review: 'Review the complete useful relationship between Blueprint, code, Program, and tests.',
 };
 
+function stackCatalogContext(pieces = []) {
+  return pieces.map(({ id, description, requires, conflicts }) => ({
+    id,
+    description,
+    requires,
+    conflicts,
+  }));
+}
+
 function requestText(value, task) {
   const request = String(value ?? '').trim();
   if (Buffer.byteLength(request, 'utf8') > 64 * 1024) {
@@ -142,6 +155,71 @@ async function generateExplanationPrompt({ instructions, program, request, root,
   };
 }
 
+async function generateStartPrompt({ instructions, program, request, root }) {
+  let blueprint;
+  try {
+    blueprint = await readBlueprint(root, { required: true });
+  } catch (error) {
+    if (error?.code !== 'BLUEPRINT_REQUIRED') throw error;
+    const files = await gitVisibleFileStates(root, { includePath: isProjectContentPath });
+    const existing = [...files.values()].some((state) => state.exists);
+    if (!existing) throw error;
+    return {
+      status: 'ready',
+      task: 'start',
+      prompt: renderPrompt({
+        instructions,
+        request,
+        context: {
+          task: 'start',
+          projectRoot: root,
+          projectKind: 'existing-uninitialized',
+          genesis: { initialized: false },
+          program: programContext(program),
+        },
+      }),
+      warnings: program.diagnostic ? [program.diagnostic] : [],
+      verificationCommands: [],
+    };
+  }
+  const [stack, index, catalog] = await Promise.all([
+    readStack(root),
+    buildProjectIndex({ projectRoot: root, write: false }),
+    listBuiltinStackPieces(),
+  ]);
+  const projectSkills = await inspectProjectSkills({ projectRoot: root, stack });
+  const newProject = stack.components.length === 0 && index.fileCount === 0;
+  return {
+    status: 'ready',
+    task: 'start',
+    prompt: renderPrompt({
+      instructions,
+      request,
+      context: {
+        task: 'start',
+        projectRoot: root,
+        projectKind: newProject ? 'new' : 'existing',
+        blueprint: {
+          path: blueprint.path,
+          description: blueprint.description,
+        },
+        stack: stackPromptContext(stack),
+        availableStackPieces: stackCatalogContext(catalog),
+        program: programContext(program),
+        codeIndex: codeIndexContext(index),
+      },
+      guidance: stack.guidance,
+      skills: renderAgentSkillCatalog(projectSkills.skills),
+    }),
+    warnings: [
+      ...(program.diagnostic ? [program.diagnostic] : []),
+      ...projectSkills.diagnostics,
+      ...index.diagnostics,
+    ],
+    verificationCommands: [],
+  };
+}
+
 export async function generateProjectPrompt({
   environment = process.env,
   projectRoot,
@@ -181,6 +259,36 @@ export async function generateProjectPrompt({
   }
 
   const program = await observeProgram(root);
+  if (task === 'start') {
+    return generateStartPrompt({
+      instructions,
+      program,
+      request: userRequest,
+      root,
+    });
+  }
+  let stack;
+  if (task === 'work') {
+    try {
+      stack = await readStack(root);
+    } catch (error) {
+      if (error?.code !== 'STACK_REQUIRED') throw error;
+      return generateStartPrompt({
+        instructions: await readInstalledAsset('start'),
+        program,
+        request: userRequest,
+        root,
+      });
+    }
+    if (stack.components.length === 0) {
+      return generateStartPrompt({
+        instructions: await readInstalledAsset('start'),
+        program,
+        request: userRequest,
+        root,
+      });
+    }
+  }
   if (['describe', 'program'].includes(task)) {
     return generateExplanationPrompt({
       instructions,
@@ -192,7 +300,7 @@ export async function generateProjectPrompt({
   }
 
   const blueprint = await readBlueprint(root, { required: true, requireDescription: true });
-  const stack = await readStack(root);
+  stack ||= await readStack(root);
   const [index, projectSkills] = await Promise.all([
     buildProjectIndex({ projectRoot: root, write: false }),
     inspectProjectSkills({ projectRoot: root, stack }),

package/src/index/stack-environment-files.js

@@ -0,0 +1,83 @@
+import { GenesisError } from './errors.js';
+import { isCanonicalProjectWorkdir } from './stack-process.js';
+
+const DOTENV_LINE = /^- Dotenv `([^`\r\n]+)`[ \t]*$/u;
+
+function invalid(environmentPath, message, line, details = {}) {
+  throw new GenesisError('STACK_ENVIRONMENT_FILES_INVALID', message, {
+    path: environmentPath,
+    ...(line === undefined ? {} : { line }),
+    ...details,
+  });
+}
+
+function environmentFilePath(value, environmentPath, line) {
+  if (value === '.' || !isCanonicalProjectWorkdir(value)) {
+    invalid(
+      environmentPath,
+      'Environment file paths must be canonical project-relative file paths.',
+      line,
+      { observed: value },
+    );
+  }
+  return value;
+}
+
+export function parseStackEnvironmentFileLines(lines, {
+  path: environmentPath = 'stack environment files',
+} = {}) {
+  if (lines === undefined) return null;
+  const entries = lines.map((line) => line.trim()).filter(Boolean);
+  if (entries.length === 1 && entries[0] === '- Nothing.') return [];
+  const files = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const source = lines[index].trim();
+    if (!source) continue;
+    const entry = source.match(DOTENV_LINE);
+    if (!entry) {
+      invalid(
+        environmentPath,
+        'Every Environment files entry must use `- Dotenv `project-relative-path``.',
+        index + 1,
+        { observed: source },
+      );
+    }
+    files.push({
+      format: 'dotenv',
+      path: environmentFilePath(entry[1], environmentPath, index + 1),
+    });
+  }
+  if (files.length === 0) {
+    invalid(environmentPath, '## Environment files needs at least one Dotenv entry.');
+  }
+  const paths = files.map((file) => file.path);
+  if (new Set(paths).size !== paths.length) {
+    invalid(environmentPath, '## Environment files contains a duplicate path.');
+  }
+  return files;
+}
+
+export function composeStackEnvironmentFiles(components, projectFiles) {
+  if (projectFiles !== null) {
+    return projectFiles.map((file) => ({ ...file, source: 'project' }));
+  }
+  const files = new Map();
+  for (const component of components) {
+    for (const file of component.environmentFiles) {
+      const existing = files.get(file.path);
+      if (existing && existing.format !== file.format) {
+        invalid(
+          `component:${component.id}`,
+          `Stack components declare incompatible environment file formats for ${file.path}.`,
+        );
+      }
+      if (!existing) {
+        files.set(file.path, {
+          ...file,
+          source: `component:${component.id}`,
+        });
+      }
+    }
+  }
+  return [...files.values()].sort((left, right) => left.path.localeCompare(right.path));
+}

package/src/index/stack-piece.js

@@ -1,5 +1,6 @@
 import { GenesisError } from './errors.js';
 import { parseStackCommandLines } from './stack-command.js';
+import { parseStackEnvironmentFileLines } from './stack-environment-files.js';
 import { parseStackLaunchLines } from './stack-launch.js';
 import { parseStackWorkspaceSetupLines } from './stack-workspace-setup.js';
 import { normalizeSource } from './utils.js';
@@ -215,6 +216,10 @@ export function parseStackPieceSource(value, {
   const deslop = textSection(all, 'Deslop');
   if (!description) invalid(piecePath, 'Stack piece needs Description.');
   const commands = parseStackCommandLines(all.get('Commands') || [], { path: piecePath });
+  const environmentFiles = parseStackEnvironmentFileLines(
+    all.has('Environment files') ? all.get('Environment files') : undefined,
+    { path: piecePath },
+  );
   const launch = parseStackLaunchLines(all.has('Launch') ? all.get('Launch') : undefined, {
     path: piecePath,
   });
@@ -232,6 +237,7 @@ export function parseStackPieceSource(value, {
     skill: skill(all, piecePath),
     resources: resources(all, piecePath),
     commands: commands.map(({ line: _line, ...command }) => command),
+    environmentFiles: environmentFiles || [],
     launchTargets: launch?.targets || [],
     workspaceSetupSteps: workspaceSetup || [],
     deslop,

package/src/index/stack-workspace-setup.js

@@ -7,6 +7,7 @@ import {
 
 const PREPARE_LINE = /^- Prepare `([^`\r\n]+)` with (.+?):[ \t]+(.+)$/u;
 const RUNTIME_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const READY_WHEN_SUFFIX = /^(.*?)[ \t]+when `([^`\r\n]+)` exists$/u;
 const WORKDIR_SUFFIX = /^(.*?)[ \t]+in `([^`\r\n]+)`$/u;
 
 function invalid(setupPath, message, line, details = {}) {
@@ -58,7 +59,7 @@ export function parseStackWorkspaceSetupLines(lines, {
     if (!entry) {
       invalid(
         setupPath,
-        'Every Workspace setup entry must use `- Prepare `label` with `runtime` [in `workdir`]: `command` `argument`...`.',
+        'Every Workspace setup entry must use `- Prepare `label` with `runtime` [in `workdir`] [when `path` exists]: `command` `argument`...`.',
         line,
         { observed: source },
       );
@@ -67,8 +68,18 @@ export function parseStackWorkspaceSetupLines(lines, {
     if (!label || /[\0\r\n]/u.test(label)) {
       invalid(setupPath, 'Workspace setup labels must be non-empty single lines.', line);
     }
-    const workdirEntry = entry[2].match(WORKDIR_SUFFIX);
-    const runtimeSource = workdirEntry ? workdirEntry[1] : entry[2];
+    const readyEntry = entry[2].match(READY_WHEN_SUFFIX);
+    const setupSource = readyEntry ? readyEntry[1] : entry[2];
+    const readyWhen = readyEntry ? readyEntry[2] : '';
+    if (readyWhen && (readyWhen === '.' || !isCanonicalProjectWorkdir(readyWhen))) {
+      invalid(
+        setupPath,
+        'Workspace setup readiness paths must be canonical project-relative paths.',
+        line,
+      );
+    }
+    const workdirEntry = setupSource.match(WORKDIR_SUFFIX);
+    const runtimeSource = workdirEntry ? workdirEntry[1] : setupSource;
     const workdir = workdirEntry ? workdirEntry[2] : '.';
     if (!isCanonicalProjectWorkdir(workdir)) {
       invalid(setupPath, 'Workspace setup workdir must be a canonical project-relative directory.', line);
@@ -86,6 +97,7 @@ export function parseStackWorkspaceSetupLines(lines, {
       argv,
       runtimeRequirements: parseRuntimeRequirements(runtimeSource, setupPath, line),
       workdir,
+      ...(readyWhen ? { readyWhen } : {}),
     });
   }
   if (steps.length === 0) {

package/src/index/stack.js

@@ -6,6 +6,10 @@ import { GenesisError } from './errors.js';
 import { readBuiltinStackCatalog } from './stack-catalog.js';
 import { parseStackCommandLines } from './stack-command.js';
 import { resolveStackPieces } from './stack-composition.js';
+import {
+  composeStackEnvironmentFiles,
+  parseStackEnvironmentFileLines,
+} from './stack-environment-files.js';
 import { composeStackLaunchTargets, parseStackLaunchLines } from './stack-launch.js';
 import {
   composeStackWorkspaceSetup,
@@ -21,7 +25,13 @@ import { sha256, stableJson, writeFileAtomic } from './utils.js';
 
 const COMPONENT_LINE = /^- `([a-z0-9]+(?:-[a-z0-9]+)*)`$/u;
 export const EMPTY_STACK_SOURCE = '# Stack\n\n## Components\n';
-const STACK_SECTIONS = new Set(['Components', 'Workspace setup', 'Commands', 'Launch']);
+const STACK_SECTIONS = new Set([
+  'Components',
+  'Environment files',
+  'Workspace setup',
+  'Commands',
+  'Launch',
+]);
 const STACK_CUSTOMIZATION_ROOT = 'genesis/stack';
 
 function parseSections(source) {
@@ -87,6 +97,7 @@ function withoutOuterBlankLines(lines = []) {
 function renderStack({
   commandLines = [],
   componentIds: componentIdsValue,
+  environmentFileLines = null,
   launchLines = null,
   workspaceSetupLines = null,
 }) {
@@ -95,6 +106,9 @@ function renderStack({
     '',
     '## Components',
     ...componentIdsValue.map((id) => `- \`${id}\``),
+    ...(environmentFileLines === null
+      ? []
+      : ['', '## Environment files', '', ...withoutOuterBlankLines(environmentFileLines)]),
     ...(workspaceSetupLines === null
       ? []
       : ['', '## Workspace setup', '', ...withoutOuterBlankLines(workspaceSetupLines)]),
@@ -129,6 +143,13 @@ export async function addStackPieces({ pieces, projectRoot }) {
   )).map(({ id }) => id);
   const commandLines = parseStackCommandLines(sections.get('Commands') || [], { path: STACK_PATH })
     .map(({ label, argv }) => `- Verify \`${label}\`: ${argv.map((value) => `\`${value}\``).join(' ')}`);
+  const environmentFileLines = sections.has('Environment files')
+    ? sections.get('Environment files')
+    : null;
+  parseStackEnvironmentFileLines(
+    environmentFileLines === null ? undefined : environmentFileLines,
+    { path: STACK_PATH },
+  );
   const launchLines = sections.has('Launch') ? sections.get('Launch') : null;
   parseStackLaunchLines(launchLines === null ? undefined : launchLines, { path: STACK_PATH });
   const workspaceSetupLines = sections.has('Workspace setup')
@@ -141,6 +162,7 @@ export async function addStackPieces({ pieces, projectRoot }) {
   const rendered = renderStack({
     commandLines,
     componentIds: selected,
+    environmentFileLines,
     launchLines,
     workspaceSetupLines,
   });
@@ -228,6 +250,11 @@ export async function readStack(projectRoot) {
   const componentCommands = components.flatMap((piece) => piece.commands);
   const commands = distinctCommands(projectCommands.length > 0 ? projectCommands : componentCommands);
   const resources = resourceDeclarations(components);
+  const projectEnvironmentFiles = parseStackEnvironmentFileLines(
+    sections.has('Environment files') ? sections.get('Environment files') : undefined,
+    { path: STACK_PATH },
+  );
+  const environmentFiles = composeStackEnvironmentFiles(components, projectEnvironmentFiles);
   const projectLaunch = parseStackLaunchLines(
     sections.has('Launch') ? sections.get('Launch') : undefined,
     { path: STACK_PATH },
@@ -243,12 +270,14 @@ export async function readStack(projectRoot) {
     identityHash: sha256(stableJson({
       components: components.map(({ id }) => id),
       commands: commands.map(({ label, argv }) => ({ label, argv })),
+      environmentFiles,
       launchTargets,
       resources,
       workspaceSetup,
     })),
     components,
     commands,
+    environmentFiles,
     launchTargets,
     workspaceSetup,
     resources,
@@ -266,6 +295,7 @@ export function stackPromptContext(stack) {
       requires: piece.requires,
     })),
     verifyCommands: stack.commands.map(({ label, argv }) => ({ label, argv })),
+    environmentFiles: stack.environmentFiles,
     launchTargets: stack.launchTargets,
     workspaceSetup: stack.workspaceSetup,
   };

package/src/index/workspace-setup.js

@@ -1,3 +1,6 @@
+import { access } from 'node:fs/promises';
+import path from 'node:path';
+
 import { gitContext } from './git.js';
 import { readStack } from './stack.js';
 import { sha256, stableJson, uniqueSorted } from './utils.js';
@@ -8,10 +11,32 @@ export async function inspectProjectWorkspaceSetup({
 } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const stack = await readStack(root);
-  const diagnostics = stack.workspaceSetup.diagnostics;
+  const diagnostics = [...stack.workspaceSetup.diagnostics];
+  if (diagnostics.length === 0) {
+    const waitingFor = [];
+    for (const step of stack.workspaceSetup.steps) {
+      if (!step.readyWhen) continue;
+      try {
+        await access(path.join(root, step.readyWhen));
+      } catch (error) {
+        if (!['ENOENT', 'ENOTDIR'].includes(error?.code)) throw error;
+        waitingFor.push(step.readyWhen);
+      }
+    }
+    if (waitingFor.length > 0) {
+      const paths = uniqueSorted(waitingFor);
+      diagnostics.push({
+        code: 'STACK_WORKSPACE_SETUP_WAITING',
+        message: `Workspace setup is waiting for project ${paths.length === 1 ? 'path' : 'paths'}: ${paths.join(', ')}.`,
+        details: { paths },
+      });
+    }
+  }
+  const waiting = diagnostics.some(({ code }) => code === 'STACK_WORKSPACE_SETUP_WAITING');
+  const blocked = diagnostics.some(({ code }) => code !== 'STACK_WORKSPACE_SETUP_WAITING');
   let status = 'unconfigured';
-  if (diagnostics.length > 0) status = 'blocked';
-  else if (stack.workspaceSetup.steps.length > 0) status = 'ready';
+  if (blocked) status = 'blocked';
+  else if (!waiting && stack.workspaceSetup.steps.length > 0) status = 'ready';
   const recipeHash = status === 'ready'
     ? sha256(stableJson({ version: 1, steps: stack.workspaceSetup.steps }))
     : '';

package/src/index.js

@@ -6,6 +6,7 @@ import { contextForProjectPaths } from './index/context.js';
 import { generateProjectPrompt } from './index/prompt.js';
 import { initializeProject } from './index/init.js';
 import { installCodexPlugin } from './index/codex-plugin.js';
+import { inspectProjectEnvironment } from './index/environment-files.js';
 import { inspectProjectLaunch } from './index/launch.js';
 import { listBuiltinStackPieces } from './index/stack-catalog.js';
 import { addStackPieces } from './index/stack.js';
@@ -72,6 +73,10 @@ export function inspectLaunch(options) {
   return inspectProjectLaunch(options);
 }
 
+export function inspectEnvironment(options) {
+  return inspectProjectEnvironment(options);
+}
+
 export function inspectWorkspaceSetup(options) {
   return inspectProjectWorkspaceSetup(options);
 }

package/stacks/pieces/jskit.md

@@ -29,7 +29,11 @@ generated files, and runtime composition.
 
 ## Workspace setup
 
-- Prepare `Install dependencies` with `nodejs`: `npm` `install`
+- Prepare `Install dependencies` with `nodejs` when `package.json` exists: `npm` `install`
+
+## Environment files
+
+- Dotenv `.env`
 
 ## Launch