genesis-compiler 1.2.28 → 1.2.29

package/README.md

@@ -200,9 +200,9 @@ complete directory into `.agents/skills/`, including its `references/`,
 must resolve within that same Skill directory after relocation; a missing
 target or path that escapes the Skill root makes the Skill invalid. The agent
 loads valid resources only when the Skill requires them. A technology does not
-need a Skill to be selectable: the curated JSKIT piece, like ordinary framework
-pieces, links its authoritative framework documentation through Stack prose and
-declares no Skill. A piece's optional `## Guidance` is concise supplemental
+need a Skill to be selectable: the curated JSKIT and Vue pieces link their
+authoritative framework documentation through Stack prose and declare no Skill.
+A piece's optional `## Guidance` is concise supplemental
 project-work guidance; it does not create or replace a generic technology
 skill.
 
@@ -518,8 +518,13 @@ The eight task types are deliberately explicit:
 - `start` opens the project conversation. For a new project it establishes what
   is being built, who or what will use or invoke it, and the first useful
   observable outcome before presenting relevant choices from the live Stack
-  catalog. A partial reply resolves only what it explicitly answers. For an
-  existing project it asks what the person wants to understand or change.
+  and engineering-profile catalogs. A partial reply resolves only what it
+  explicitly answers. An existing project receives none of those new-project
+  questions or catalogs. Its opening contains the full Blueprint, concise
+  selected Stack and Program summaries, and full selected Guidance separated by
+  component headings; detailed Program modules, sources, operations, indexes,
+  and skills are loaded later with `genesis context <relevant-path...>`. It
+  checks `genesis stack list` before proposing an additional technology.
 - `adopt` imports an existing application's factual operational and product
   contracts into Genesis metadata. It composes technology-specific Adoption
   requirements from the selected Stack and does not change application code.
@@ -645,7 +650,10 @@ General `Guidance` enriches implementation, review, Program, description, and
 cleanup tasks; `Adoption` adds import-only requirements; `Post-change` adds
 work to finish in the original implementation turn; `Deslop` adds
 technology-specific cleanup rules to Genesis's invariant behavior-preserving
-contract. None shadows an official generic technology skill or assumes that an
+contract. When several components contribute one of these prose fields,
+Genesis retains each complete contribution under its component heading in
+dependency-first selected order; it does not blend or semantically deduplicate
+their instructions. None shadows an official generic technology skill or assumes that an
 upstream skill contains every rule Genesis needs.
 
 Genesis core contains no Stack pieces and no database, framework, language, or

package/docs/prompt-integration.md

@@ -17,9 +17,16 @@ await currentAgent.send(work.prompt);
 
 Tasks are `start`, `adopt`, `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
+project from its selected Stack and Git-visible project paths without building
+the code index. A new project gets the product questions and live Stack and
+engineering-profile catalogs. An existing project gets none of that
+new-project launcher or catalog: its opening JSON contains the full Blueprint,
+selected component summaries, and only bounded Program status, subsystem names,
+and a module count. The complete effective Guidance remains present once under
+component headings. Exact Program modules, sources, project contracts, indexed
+functions, verification commands, and skills are deferred to `genesis context
+<relevant-path...>`. A new technology request goes through `genesis stack list`
+before selection. 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
@@ -33,8 +40,9 @@ Genesis keeps each instruction at one useful level:
 - `skills/genesis-project/`, `skills/genesis-program/`, and
   `skills/genesis-deslop/` are the reusable workflow sources copied into each
   project's `.agents/skills/` directory.
-- `prompts/<task>.txt` is a task launcher. It selects the relevant
-  workflow skill and states only that turn's edit boundary.
+- `prompts/<task>.txt` is a task launcher. `start.txt` is only the common opening
+  seam; one of its new, existing, or existing-uninitialized launchers is appended
+  after classification. Each launcher states only its own project kind's work.
 - a declared Stack package's `stacks/pieces/<component>.md` supplies concise Description, supplemental
   Guidance, Adoption requirements, initial operation proposals, Deslop overlays,
   structural Indexers, and an optional authoritative Agent Skill source.
@@ -50,7 +58,8 @@ Detailed technology manuals belong to the technology's authoritative
 documentation, which Stack prose may link directly. A technology may also
 offer a separately installable Skill with its own `references/` directory.
 Concise rules needed in project prompts belong in Stack `Guidance`; they are
-composed without creating a colliding generic skill.
+composed dependency-first without semantic blending and retain a heading for
+each contributing component.
 
 ## Existing projects
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.2.28",
+  "version": "1.2.29",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with project agent guidance.",
   "repository": {
@@ -34,6 +34,9 @@
     "prompts/program.txt",
     "prompts/review.txt",
     "prompts/start.txt",
+    "prompts/start-existing.txt",
+    "prompts/start-existing-uninitialized.txt",
+    "prompts/start-new.txt",
     "prompts/work.txt",
     "plugins/genesis",
     "plugins/opencode",

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

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

package/prompts/start-existing-uninitialized.txt

@@ -0,0 +1,8 @@
+This is an existing project without Genesis project context. Do not ask
+new-project product-discovery questions. Ask what the person wants to understand
+or change and strongly recommend preparing the project for guided editing before
+substantial work. Explain in product language that preparation preserves the
+implementation while importing its current product, setup, run, data, preview,
+and verification facts. Do not require the person to know Genesis terminology or
+type a command. If they approve, run the Genesis `adopt` operation and follow its
+prompt. If they decline, continue normally and do not repeat the recommendation.

package/prompts/start-existing.txt

@@ -0,0 +1,23 @@
+The project already exists. Do not ask new-project product-discovery questions
+and do not offer an unselected technology catalog. Use the Blueprint as product
+intent, the selected Stack summary and full guidance as technical direction, and
+the compact Program status only as orientation. If USER REQUEST is actionable,
+proceed with it. Otherwise ask what the person wants to understand or change.
+
+After locating the relevant source, run the Genesis `context <relevant-path...>`
+operation before implementation to load the exact Program modules, project
+contracts, indexed functions, verification commands, and applicable skills.
+
+If the user requests an unselected technology, run the Genesis `stack list`
+operation first. For one exact match, ask whether to add it and prepare the
+project with its official guidance; only after confirmation run `stack add
+<piece...>` and follow its preparation prompt. If nothing matches, use the
+technology's authoritative documentation without inventing a component.
+
+When no Stack is selected, inspect the project's actual scripts, build and setup
+files, server entrypoint, and readiness behavior before recording a technology.
+Component proposals are not evidence, and selecting a component does not port an
+older implementation. Preserve evidenced project-owned contracts in their
+consumer's current schema. If the existing implementation is not usefully
+explained, recommend the Genesis description path instead of pretending its
+intent or operations are known.

package/prompts/start-new.txt

@@ -0,0 +1,27 @@
+The project is new. Before technology research or source creation, establish
+what is being built, who or what will use or invoke it, and the first observable
+useful outcome. Ask at most three concise questions at a time, and do not repeat
+facts already supplied by the user. A Stack choice is not product intent.
+
+Use `availableStackPieces` to offer only relevant technology choices in product
+language. Never silently select one. If the user names an unselected technology,
+run the Genesis `stack list` operation first. For one exact match, ask whether to
+add it and prepare the project with its official guidance. On confirmation, run
+the Genesis `stack add <piece...>` operation, follow its preparation prompt in
+this task, then run `context .` or `context <relevant-path>` and load any
+applicable installed skill. Never infer an install command from a component id.
+If the user declines, do not ask again; if nothing matches, use the technology's
+authoritative documentation without inventing a component.
+
+Establish the non-technical Blueprint before implementation. If product intent
+is clear while Stack is empty, present the relevant Stack choices in this same
+turn. The default `focused.v1` engineering profile suits ordinary work; use
+`availableEngineeringProfiles` only when the user requests another approach or
+the product has material long-lived compatibility, operational, security,
+reliability, or compliance constraints. Apply an explicit choice with the
+Genesis `engineering set <profile>` operation.
+
+This opening owns product direction and Stack selection, not final verification.
+Do not run the Genesis `verify` operation before implementation exists. Use
+`check` only when structural validation is useful. Once direction and Stack are
+clear, follow one smallest implementation path through the selected guidance.

package/prompts/start.txt

@@ -1,87 +1,5 @@
 Read and follow `.agents/skills/genesis-project/SKILL.md` completely.
 
-This is the project-opening conversation. For a new project, do not begin
-technology research or create source until the user has made clear what is
-being built, who or what will use or invoke it, and the first observable useful
-outcome. Ask only unresolved high-impact questions. A reply confirms only what
-it explicitly answers; Stack confirmation is not product intent.
-
-When the user explicitly names a technology, framework, language, or database
-that is not selected, make the existing Genesis `stack list` operation the
-first technology action. If one catalog component exactly matches that choice,
-ask: "<Technology> is available in Genesis. Would you like me to add it to this
-project and prepare the app with its official guidance?" Do not run `stack add
-<piece...>` without that confirmation. If confirmed, add it, let Genesis apply
-its declared dependency closure and synchronize any skill the component
-declares. Follow the preparation prompt returned by `stack add` in this same
-task: make each materialized project contract true or replace a complete
-section with evidenced reality. Then run `context .` (or the relevant source
-path once source exists), load the applicable installed skill if present, and
-follow the technology-owned guidance to prepare actual project dependencies.
-Never infer an install command from a component id. If declined, continue
-without adding it or asking again.
-If no component matches, do not invent one; continue normally using
-authoritative technology documentation.
-
-When `projectKind` is `new`, establish what is being built, who or what will use
-or invoke it, and its first observable useful outcome. Ask up to three concise,
-high-impact questions at a time, and ask access, data, platform, or interface
-questions only when they are material to that product. Use
-`availableStackPieces` to present only the relevant choices, explain them in
-product language, and let the user decide. Never silently select a technology.
-After the user confirms the proposed component selection, use the Genesis
-`stack add <piece...>` operation; 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.
-The default `focused.v1` engineering profile is already suitable for ordinary
-work, so do not force a separate profile question. When the user asks for a
-different engineering approach, or the product clearly has long-lived
-compatibility, operational, security, reliability, or compliance constraints,
-use `availableEngineeringProfiles` to explain only the relevant choices in
-product language. After an explicit choice, run the Genesis `engineering set
-<profile>` operation; do not invent or duplicate a built-in profile. Record
-additional explicit obligations in `genesis/engineering.md` under Project
-requirements.
-This opening turn owns product direction and Stack selection, not final
-verification. Do not run the Genesis `verify` operation before implementation
-exists. If structural validation is useful, run the Genesis `check` operation;
-consumer-owned operations remain governed by their own tools and must not be
-inferred here.
-
-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 an existing implementation has no selected Stack yet, inspect its actual
-package scripts, build files, setup commands, server entrypoint, and readiness
-route before recording the user's technology choice. Materialized component
-proposals describe that component's current operational foundation; selecting
-the component does not port an older implementation to it. If the existing
-facts differ, replace the complete project-owned section using the consumer's
-current schema and the code that exists. Never report a proposed operation as
-usable merely because the component was selected, and never add compatibility
-implementation without the user asking for a port.
-
-When `projectKind` is `existing-uninitialized`, ask what the user wants to
-understand or change and strongly recommend preparing the existing project for
-guided editing before substantial work. Explain in product language that this
-preserves the implementation while importing its current setup, run, database,
-preview, verification, and product context. Do not require the user to know
-Genesis terminology or type a command. If they approve, run the Genesis `adopt`
-operation yourself and follow its adoption prompt. If they decline, continue
-normally and do not repeat the recommendation.
-
-If the request already contains an unambiguous product description and an
-explicit Stack choice, establish the Blueprint and ask for the component
-confirmation described above before applying that choice. Otherwise this is a
-conversational turn: ask, listen, and preserve the source.
-
-Once product direction and any relevant Stack selection are clear, choose one
-smallest implementation path through the applicable technology guidance, or
-authoritative technology documentation when the catalog has no match, and read
-only what that path requires. Do not survey alternative foundations, clone
-whole technology repositories, inspect unrelated package internals, or
-delegate research unless one concrete failure requires one exact investigation.
+This is the project-opening conversation. Follow only the project-kind
+instructions below. Treat USER REQUEST as the person's actual request, preserve
+what it already establishes, and ask only unresolved high-impact questions.

package/src/index/assets.js

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

package/src/index/codex-hooks.js

@@ -3,9 +3,8 @@ import path from 'node:path';
 
 import { GenesisError } from './errors.js';
 import { gitContext } from './git.js';
-import { isProjectContentPath } from './paths.js';
-import { runGit } from './process.js';
-import { normalizeRelative, pathState, writeFileAtomic } from './utils.js';
+import { classifyProjectKind } from './project-files.js';
+import { pathState, writeFileAtomic } from './utils.js';
 
 const HOOKS_PATH = '.codex/hooks.json';
 const LEGACY_GENESIS_HOOKS_DESCRIPTION = 'Genesis project hooks.';
@@ -90,20 +89,15 @@ export async function installCodexHooks({ projectRoot } = {}) {
   return { status: 'updated', changedFiles: [HOOKS_PATH] };
 }
 
-function zeroPaths(buffer) {
-  return [...new Set(buffer.toString('utf8').split('\0').map(normalizeRelative).filter(Boolean))];
-}
-
 export async function codexAdoptionRecommendation({ projectRoot = process.cwd() } = {}) {
   let root;
   try { root = (await gitContext(projectRoot)).repositoryRoot; } catch { return { status: 'not-applicable', output: '' }; }
   if ((await pathState(path.join(root, 'genesis/blueprint.md'))).exists) {
     return { status: 'not-applicable', output: '' };
   }
-  const files = zeroPaths((await runGit(root, [
-    'ls-files', '-z', '--cached', '--others', '--exclude-standard',
-  ])).stdout).filter(isProjectContentPath);
-  if (files.length === 0) return { status: 'not-applicable', output: '' };
+  if (await classifyProjectKind({ projectRoot: root }) === 'new') {
+    return { status: 'not-applicable', output: '' };
+  }
   return {
     status: 'ready',
     output: [

package/src/index/context.js

@@ -31,18 +31,13 @@ function stackSummary(stack) {
 }
 
 function stackGuidance(stack) {
-  const pieces = stack.components.filter(({ guidance }) => guidance);
-  if (pieces.length === 0) return [];
+  if (!stack.guidance) return [];
   return [
     '',
     '## Selected Stack guidance',
     '',
-    ...pieces.flatMap(({ id, guidance }) => [
-      `### ${id}`,
-      '',
-      guidance,
-      '',
-    ]),
+    stack.guidance,
+    '',
   ];
 }
 

package/src/index/opencode-plugin.js

@@ -2,9 +2,9 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 
 import { gitContext } from './git.js';
+import { OPENCODE_PLUGIN_PATH } from './paths.js';
 import { writeFileAtomic } from './utils.js';
 
-const OPENCODE_PLUGIN_PATH = '.opencode/plugins/genesis-project-guidance.js';
 const OPENCODE_PLUGIN_SOURCE = new URL('../../plugins/opencode/project-guidance.js', import.meta.url);
 
 async function existingSource(location) {

package/src/index/paths.js

@@ -4,6 +4,7 @@ export const STACK_PATH = 'genesis/stack.md';
 export const PROGRAM_ROOT = 'genesis/program';
 export const PROJECT_VERSION_PATH = 'genesis/version';
 export const VERIFICATION_PATH = '.genesis/verification.json';
+export const OPENCODE_PLUGIN_PATH = '.opencode/plugins/genesis-project-guidance.js';
 
 export function isProjectContentPath(file) {
   const first = file.split('/')[0];

package/src/index/project-files.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 
+import { isProjectContentPath, OPENCODE_PLUGIN_PATH } from './paths.js';
 import { runGit } from './process.js';
 import { pathState } from './utils.js';
 
@@ -22,3 +23,14 @@ export async function gitVisibleFileStates(projectRoot, { includePath = () => tr
   }
   return states;
 }
+
+/** Classifies opening behavior from cheap Git-visible paths and selected Stack state. */
+export async function classifyProjectKind({ projectRoot, stackComponents = [] } = {}) {
+  if (stackComponents.length > 0) return 'existing';
+  const existing = (await visiblePaths(projectRoot)).some((file) => (
+    isProjectContentPath(file)
+    && file !== OPENCODE_PLUGIN_PATH
+    && !file.split('/').includes('node_modules')
+  ));
+  return existing ? 'existing' : 'new';
+}

package/src/index/prompt.js

@@ -17,8 +17,7 @@ import { inspectVerification } from './project-state.js';
 import { missingStackResources } from './stack-preflight.js';
 import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { stableJson } from './utils.js';
-import { gitVisibleFileStates } from './project-files.js';
-import { isProjectContentPath } from './paths.js';
+import { classifyProjectKind } from './project-files.js';
 
 const TASKS = new Set(['start', 'adopt', 'work', 'deslop', 'program', 'blueprint', 'describe', 'review']);
 const DEFAULT_REQUEST = {
@@ -83,6 +82,26 @@ function programContext(program) {
   };
 }
 
+function startProgramContext(program) {
+  return {
+    status: program.status,
+    subsystems: program.subsystems,
+    moduleCount: program.modules.length,
+    ...(program.diagnostic ? { diagnostic: program.diagnostic } : {}),
+  };
+}
+
+function startStackContext(stack) {
+  return {
+    components: stack.components.map(({ id, description }) => ({ id, description })),
+  };
+}
+
+async function startInstructions(instructions, projectKind) {
+  const specific = await readInstalledAsset(`start-${projectKind}`);
+  return `${instructions.trim()}\n\n${specific.trim()}`;
+}
+
 function codeIndexContext(index) {
   return {
     machineCity: {
@@ -231,21 +250,17 @@ async function generateStartPrompt({
   root,
   stackPackages,
 }) {
-  const availableEngineeringProfiles = (await listEngineeringProfileCatalog())
-    .map(({ id, name, description }) => ({ id, name, description }));
   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;
+    if (await classifyProjectKind({ projectRoot: root }) === 'new') throw error;
     return {
       status: 'ready',
       task: 'start',
       prompt: renderPrompt({
-        instructions,
+        instructions: await startInstructions(instructions, 'existing-uninitialized'),
         request,
         context: {
           task: 'start',
@@ -253,8 +268,6 @@ async function generateStartPrompt({
           projectKind: 'existing-uninitialized',
           genesis: { initialized: false },
           engineering: engineeringPromptContext(engineering),
-          availableEngineeringProfiles,
-          program: programContext(program),
         },
         engineeringGuidance: engineering.guidance,
       }),
@@ -263,42 +276,51 @@ async function generateStartPrompt({
     };
   }
   const stack = await readStack(root, { stackPackages });
+  const projectKind = await classifyProjectKind({
+    projectRoot: root,
+    stackComponents: stack.components,
+  });
   const availableStackPackages = [...new Set([...stack.stackPackages, ...stackPackages])];
-  const [index, catalog] = await Promise.all([
-    buildProjectIndex({ projectRoot: root, stackPackages, write: false }),
-    listStackCatalogPieces({ projectRoot: root, stackPackages: availableStackPackages }),
+  const [catalog, availableEngineeringProfiles, projectSkills, renderedInstructions] = await Promise.all([
+    projectKind === 'new'
+      ? listStackCatalogPieces({ projectRoot: root, stackPackages: availableStackPackages })
+      : Promise.resolve([]),
+    projectKind === 'new'
+      ? listEngineeringProfileCatalog()
+        .then((profiles) => profiles.map(({ id, name, description }) => ({ id, name, description })))
+      : Promise.resolve([]),
+    inspectProjectSkills({ projectRoot: root, stack }),
+    startInstructions(instructions, projectKind),
   ]);
-  const projectSkills = await inspectProjectSkills({ projectRoot: root, stack });
-  const newProject = stack.components.length === 0 && index.fileCount === 0;
   return {
     status: 'ready',
     task: 'start',
     prompt: renderPrompt({
-      instructions,
+      instructions: renderedInstructions,
       request,
       context: {
         task: 'start',
         projectRoot: root,
-        projectKind: newProject ? 'new' : 'existing',
+        projectKind,
         blueprint: {
           path: blueprint.path,
           description: blueprint.description,
         },
         engineering: engineeringPromptContext(engineering),
-        availableEngineeringProfiles,
-        stack: stackPromptContext(stack),
-        availableStackPieces: stackCatalogContext(catalog, hiddenStackPieces),
-        program: programContext(program),
-        codeIndex: codeIndexContext(index),
+        stack: startStackContext(stack),
+        ...(projectKind === 'new'
+          ? {
+            availableEngineeringProfiles,
+            availableStackPieces: stackCatalogContext(catalog, hiddenStackPieces),
+          }
+          : { program: startProgramContext(program) }),
       },
       engineeringGuidance: engineering.guidance,
       guidance: stack.guidance,
-      skills: renderAgentSkillCatalog(projectSkills.skills),
     }),
     warnings: [
       ...(program.diagnostic ? [program.diagnostic] : []),
       ...projectSkills.diagnostics,
-      ...index.diagnostics,
     ],
     verificationCommands: [],
   };

package/src/index/stack.js

@@ -271,8 +271,8 @@ export async function materializeProjectStackContracts({ projectRoot, stackPacka
 
 function composedProse(components, field) {
   return components
-    .map((piece) => piece[field] || '')
-    .filter(Boolean)
+    .filter((piece) => piece[field])
+    .map((piece) => `### \`${piece.id}\`\n\n${piece[field]}`)
     .join('\n\n');
 }