genesis-compiler 1.0.0 → 1.2.0

package/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "genesis",
+  "interface": {
+    "displayName": "Genesis"
+  },
+  "plugins": [
+    {
+      "name": "genesis",
+      "source": {
+        "source": "local",
+        "path": "./plugins/genesis"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

package/README.md

@@ -0,0 +1,443 @@
+# Genesis
+
+Genesis is an agent-independent prompt, code-index, and verification companion
+for local codebases. It combines product intent, concise codebase explanation,
+selected technology guidance, an existing-function inventory, and an optional
+user request into a complete prompt for the coding agent you already use.
+
+Genesis outputs text. The agent or host you already use owns execution and
+interaction.
+
+## Project files
+
+```text
+genesis/
+  blueprint.md       non-technical product intent
+  stack.md           selected technology guidance, checks, setup, and launch data
+  stack/             optional per-component Description, Guidance, and Deslop customization
+  program/           concise explanations grouped into conceptual subsystems
+.agents/skills/
+  genesis-*          Genesis workflow skills
+  <technology>/      authoritative skills installed by selected Stack pieces
+.codex/hooks.json    optional project-local Codex lifecycle integration
+.genesis/
+  machine-city.json  derived detailed source and function map
+  program-city.json  derived simple subsystem and operation map
+```
+
+Program paths describe public operations rather than languages or source
+layout:
+
+```text
+genesis/program/notes/list-notes.md
+genesis/program/notes/create-note.md
+```
+
+The directory is a conceptual subsystem. Each file describes one public
+operation provided by that subsystem: an exported method, API action, route,
+command, UI operation, or equivalent entry point. Each module cites one or more
+real files under `## Sources`. There is no 1:1 source mapping: one operation may
+span several files, helper files may be omitted, and one source may support
+multiple operations.
+
+An optional `## Implementation map` records only the internal helpers and seams
+that materially help a future agent change or debug that operation. It is
+informational, not part of the public contract, and `check` does not pretend to
+prove it current. Program omits incidental framework glue, generated files,
+tests, fixtures, and migrations. It is useful documentation, not proof that it
+completely or correctly explains the implementation.
+
+## Start
+
+Genesis requires Node.js 22 or newer and Git.
+
+For an existing codebase, `adopt` is the direct entry point:
+
+```bash
+cd my-existing-project
+git init                         # if needed
+genesis adopt "Optional product guidance"
+```
+
+It preserves the implementation, initializes the Genesis files and local
+hooks, and prints the `describe` prompt that creates the first useful Blueprint
+and Program. Give that prompt to the agent already working in the repository.
+For a large codebase, the prompt explicitly lets that agent decide whether to
+delegate inspection to subagents and requires it to synthesize one coherent
+result. “Adopt” is intentional: Genesis neither imports nor moves the project.
+
+For a new or empty project, initialize first and write the product intent:
+
+```bash
+cd my-project
+git init                         # if needed
+genesis init
+vi genesis/blueprint.md
+codex
+```
+
+Codex users may also install Genesis's optional discovery plugin once:
+
+```bash
+genesis codex install
+```
+
+When Codex opens a nonempty Git project without `genesis/blueprint.md`, the
+plugin's `SessionStart` hook runs before the first user prompt and adds a strong
+instruction to recommend `genesis adopt`. Codex cannot display an ordinary
+assistant reply until the user speaks, so the recommendation appears in its
+first reply. It never runs adoption without approval and does nothing in an
+empty or already-adopted project.
+
+`genesis init` creates an empty Blueprint, an empty optional Stack, three
+project Agent Skills, and project-local Codex hooks. The skills are ordinary
+[Agent Skills](https://agentskills.io): `genesis-project`, `genesis-program`,
+and `genesis-deslop`, each with standard `SKILL.md` and `agents/openai.yaml`
+metadata. Open `/hooks` once in Codex to review and trust the hooks. After
+that, use Codex normally. No technology is assumed until you explicitly select
+Stack components:
+
+```bash
+genesis stack add nodejs         # or jskit jskit-mysql
+```
+
+Genesis does not install substitute generic `nodejs`, `vue`, `php`, or similar
+skills. Official, user, or host skills retain their normal names. A Stack piece
+may instead name one authoritative technology skill; Genesis copies that
+complete directory into `.agents/skills/`, including its `references/`,
+`scripts/`, `assets/`, and agent metadata. The agent loads those resources only
+when the skill requires them. For example, the JSKIT piece installs the JSKIT
+package's own `jskit` skill. A piece's optional `## Guidance` is concise
+supplemental project-work guidance; it does not create or replace a generic
+technology skill.
+
+`.agents/skills/.genesis-managed.json` records only copies Genesis owns.
+Genesis never overwrites an unmanaged skill and preserves locally modified
+managed skills. Run `genesis init` after manually editing `genesis/stack.md`,
+or use `genesis stack add`, to synchronize selected skills.
+
+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 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;
+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,
+abstract runtime requirements, `{host}`/`{port}` substitutions, and an optional
+application-owned Preview identity block. Concrete components may provide a
+default: `jskit` declares build followed by `npm start`; generic `nodejs` and
+`php` do not guess. Genesis starts nothing itself. It returns preview identity
+command metadata and environment variable names, never their values. The host
+continues to own pinned runtimes, ports, processes, readiness, identity-command
+execution and secrets, browser binaries, Git, and credentials. See
+[`docs/stack-components.md`](docs/stack-components.md) for the v1 contract.
+
+At session start, Codex receives only a short explanation of how Genesis is
+organized. After it locates the source involved in a request, it can load the
+specific explanatory and technology context with:
+
+```bash
+genesis context src/path/to/file
+```
+
+Before introducing another helper or public operation, query the current
+function inventory:
+
+```bash
+genesis index normalizeNote
+genesis index src/notes
+```
+
+`genesis index` regenerates two deterministic projections. Machine City is the
+detailed physical view: indexed files, line and byte weights, public and
+internal functions or methods, signatures, source/test role, language, and
+extractor provenance. Program City is intentionally smaller: conceptual
+subsystems, Program operations, informational helper maps, and links to their
+implementing source files.
+Both are derived JSON, not receipts, authority, or correctness claims. An
+extractor warning does not stop ordinary work.
+
+The selected Stack decides which structural extractors run. Genesis uses the
+Tree-sitter-backed [ast-grep JavaScript API](https://ast-grep.github.io/guide/api-usage/js-api.html)
+through one shared engine. Built-in adapters cover JavaScript/TypeScript,
+Python, Java, C#, C/C++, PHP, Go, Rust, Ruby, Kotlin, and Shell. A future technology
+adds its adapter through its Stack piece rather than teaching Genesis prompts
+to parse that language.
+
+At the end of a turn that changed Git-visible project files, the Stop hook asks
+Codex for two separate, bounded follow-up turns. The first reconciles the
+Blueprint and affected Program explanations from the changed paths and actual
+Git diff, then Genesis deterministically refreshes both City projections. The
+second performs the focused, behavior-preserving Deslop pass, after which both
+Cities are refreshed again to reflect any cleanup. A project with no selected
+Stack uses only the `genesis-deslop` skill. Selected Stack components enrich
+reconciliation and cleanup with their general Guidance, and enrich cleanup
+further with technology-specific Deslop guidance.
+
+The hook never starts another Codex process. Its small per-session phase is
+limited to `implementation -> reconcile -> deslop -> done`, so it cannot keep
+continuing recursively. Question-only and unchanged turns finish normally.
+
+Projects can customize a selected technology through its matching file, such
+as `genesis/stack/jskit.md`:
+
+```markdown
+# Stack customization: jskit
+
+## Add
+
+### Description
+
+Additional project-specific context about how JSKIT is used here.
+
+### Guidance
+
+- Additional project-specific implementation and review guidance.
+
+### Deslop
+
+- Additional project-specific cleanup guidance.
+
+## Override
+
+### Description
+
+A replacement for the installed JSKIT description.
+
+### Guidance
+
+- Replacement installed implementation and review guidance.
+
+### Deslop
+
+- Replacement installed cleanup guidance.
+```
+
+Every field is optional. For each field, Genesis uses the installed value,
+replaces it when `Override` supplies that field, then appends the corresponding
+`Add` content. Customization affects only `Description`, `Guidance`, and
+`Deslop`; component dependencies, Agent Skill source, resources, and
+verification commands retain their installed contracts. `genesis stack add`
+preserves these matching customization files.
+
+Prompt generation remains available for other agents and explicit tasks:
+
+```bash
+genesis prompt
+```
+
+Give the printed prompt to Vibe64 or another coding agent with access to the
+project. Review ordinary edits through Git.
+
+An immediate improvement request can be included directly:
+
+```bash
+genesis prompt "Add filtering by note title"
+```
+
+## Prompt tasks
+
+```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"
+genesis prompt --task program                       # refresh explanation
+genesis prompt --task blueprint "Start on notes"   # update product intent
+genesis prompt --task describe                      # create/refresh Blueprint and complete Program
+genesis prompt --task review                        # compare intent, code, and explanation
+```
+
+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
+  automatic Deslop turn after their separate explanatory reconciliation turn.
+- `program` edits only `genesis/program/` to explain the code that exists, with
+  selected Stack guidance available for technology-specific correctness.
+- `blueprint` edits only `genesis/blueprint.md` from explicit user intent. It
+  must not infer product requirements from accidental implementation behavior.
+- `describe` creates or refreshes both the non-technical Blueprint and the
+  complete useful Program from the current codebase, optional user guidance,
+  and selected Stack guidance where it affects accurate explanation.
+- `review` is read-only. It asks the agent to compare Blueprint, code, Program,
+  and tests, identify contradictions and gaps, and distinguish evidence from
+  inference.
+
+Prompt generation is read-only. Missing external resources are reported in
+the prompt but do not prevent its generation. Genesis never invents values.
+
+Use `--json` to receive the prompt and its machine-readable context as one
+object.
+
+## Stack
+
+List and select the built-in Stack components:
+
+```bash
+genesis stack list
+genesis stack add jskit jskit-mysql
+```
+
+`genesis/stack.md` records component ids and optional project verification
+commands. Selecting no components is valid. Built-in components include the
+eleven common language families listed above, plus Vue, MySQL, JSKIT, and JSKIT
+with MySQL. Components may contribute:
+
+- a concise description and supplemental Guidance used across relevant tasks;
+- one authoritative Agent Skill directory when the component owns one;
+- generic external-resource requirements;
+- cleanup advice used by explicit and automatic Deslop prompts;
+- structural code indexers used by Machine City and function lookup;
+- default verification commands.
+
+Technology-specific supplemental rules intentionally remain in Stack pieces.
+General `Guidance` enriches implementation, review, Program, description, and
+cleanup tasks; `Deslop` adds cleanup-only rules. Neither shadows an official
+generic technology skill nor assumes that an upstream skill contains every rule
+Genesis needs.
+
+Genesis core contains no MySQL, JSKIT, Vue, Laravel, or other platform-specific
+controller behavior. See [Stack components](docs/stack-components.md).
+
+## Verification
+
+Run the Stack's declared checks explicitly:
+
+```bash
+genesis verify
+```
+
+Genesis first evaluates generic Stack resource declarations, then runs each
+declared command without a shell. A complete successful run writes only
+`.genesis/verification.json`, recording:
+
+- the exact Git-visible code hash;
+- the selected Stack hash;
+- the commands that passed.
+
+The evidence becomes stale when code, selected components, declared resources,
+or verification commands change. Description, Guidance, Agent Skill, and Deslop
+prose do not rewrite what an already-run command proved. A failed verification
+removes prior passing evidence before running. Verification does not claim
+whole-product correctness.
+
+A project can replace component defaults in `genesis/stack.md`:
+
+```markdown
+## Commands
+
+- Verify `tests`: `npm` `test`
+- Verify `build`: `npm` `run` `build`
+```
+
+## Inspection
+
+```bash
+genesis check
+```
+
+`check` is read-only. It reports only structural or recorded facts:
+
+- Blueprint and Stack validity;
+- selected Agent Skill presence and structural validity;
+- Program presence and structural validity;
+- missing Stack-declared environment inputs (without claiming the service is
+  reachable);
+- verification evidence as `current`, `stale`, `missing`, `invalid`, or
+  `unconfigured`.
+
+Here, “valid” means parseable and internally consistent: referenced source
+files exist, declared environment inputs are non-placeholder, and recorded
+hashes match. It does not mean that the product behavior makes sense. Generate
+`genesis prompt --task review` for that semantic, evidence-based comparison.
+
+Genesis does not label Program semantically current. Program is ordinary
+Markdown reviewed through Git.
+
+## Public API
+
+```js
+import {
+  adoptProject,
+  addStack,
+  check,
+  generatePrompt,
+  getContext,
+  indexCodebase,
+  initialize,
+  inspectEnvironment,
+  inspectLaunch,
+  inspectWorkspaceSetup,
+  installCodex,
+  listStackPieces,
+  verify,
+} from 'genesis-compiler';
+```
+
+`initialize()` installs the project files, Genesis workflow skills, selected
+Stack skills, and local Codex hooks.
+`adoptProject()` also returns the initial `describe` prompt for an existing
+codebase. `installCodex()` installs the optional global discovery plugin.
+`getContext()` resolves source paths to the Program modules that cite them,
+the functions already declared there, selected Stack guidance, available Agent
+Skills, and verification commands. `indexCodebase()` regenerates or returns the
+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. 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.
+
+A host such as Vibe64 can send the generated prompt to its existing agent:
+
+```js
+const work = await generatePrompt({
+  projectRoot,
+  task: 'work',
+  request: userMessage,
+});
+
+await currentAgent.send(work.prompt);
+```
+
+The host retains model choice, conversation context, reasoning presentation,
+steering, interruption, permissions, and lifecycle ownership.
+
+## Promise
+
+Genesis generates transparent context-rich prompts, performs deterministic
+project operations, and records exact verification evidence. Code, tests, Git
+review, and the user's chosen agent remain responsible for implementation. It
+does not claim universal semantic convergence, exhaustive coverage, or
+whole-product correctness.

package/bin/genesis.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+import process from "node:process";
+
+import { runCli } from "../src/cli.js";
+
+let stdoutClosed = false;
+process.stdout.on("error", (error) => {
+  if (error?.code !== "EPIPE") throw error;
+  stdoutClosed = true;
+  process.exitCode = 0;
+});
+
+const status = await runCli(process.argv.slice(2));
+process.exitCode = stdoutClosed ? 0 : status;

package/docs/assurance-model.md

@@ -0,0 +1,26 @@
+# Assurance model
+
+Genesis reports only facts it can establish mechanically:
+
+1. Blueprint, Stack, and Program files satisfy their small structural formats.
+2. Program operations live in conceptual subsystem directories and cite real
+   source files. Optional helper maps are not mechanically certified.
+3. Stack-declared environment inputs are present and non-placeholder. This does
+   not prove that an external service is reachable; a verification command must
+   establish that when it matters.
+4. Named verification commands exited successfully against one exact code and
+   Stack identity.
+5. Selected project Agent Skills have valid standard metadata and exist at the
+   expected paths. Genesis preserves unmanaged and locally customized skills
+   rather than claiming ownership of them.
+6. Machine City records what selected structural parsers observed, and Program
+   City projects the Program modules and source citations that exist. Neither
+   proves semantic equivalence, complete dynamic dispatch, or true duplication.
+
+Prompt text, Stack Description/Guidance/Deslop prose, Program prose, Agent Skill
+content, and agent output are not assurance evidence. Genesis does not claim
+that product intent and code have converged, that Program is complete or
+semantically current, or that passing checks prove the whole product correct.
+
+Git remains the review and recovery boundary. The host running the generated
+prompt owns the agent and its interaction.

package/docs/prompt-integration.md

@@ -0,0 +1,98 @@
+# Prompt integration
+
+Genesis does not start or manage an AI agent. A host asks Genesis for a prompt
+and sends that prompt to the conversation it already owns:
+
+```js
+import { generatePrompt } from 'genesis-compiler';
+
+const work = await generatePrompt({
+  projectRoot,
+  task: 'work',
+  request: userMessage,
+});
+
+await currentAgent.send(work.prompt);
+```
+
+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.
+
+## Instruction sources
+
+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 short task launcher. It selects the relevant
+  workflow skill and states only that turn's edit boundary.
+- `stacks/pieces/<component>.md` supplies concise Description, supplemental
+  Guidance, Resources, Deslop overlays, structural Indexers, verification
+  Commands, and an optional authoritative Agent Skill source.
+- `genesis/blueprint.md`, `genesis/program/`, and `genesis/stack.md` are the
+  project's own intent, explanation, and selected technical composition.
+- The generated JSON block contains current structural facts and warnings.
+
+Detailed technology manuals belong in the technology skill's `references/`
+directory. Concise rules Genesis needs beyond that skill belong in Stack
+`Guidance`; they are composed into relevant prompts without creating a
+colliding generic skill.
+
+## Existing projects
+
+`genesis adopt [product guidance...]` is the explicit starting point for a
+nonempty project. It preserves source, calls the same idempotent initialization
+used by `genesis init`, and prints a `describe` prompt for the current agent to
+follow. The description prompt may direct a large-project agent to use
+subagents at its discretion, but the primary agent must reconcile their work
+into one Blueprint and one subsystem-oriented Program.
+
+Codex users can run `genesis codex install` once to install the packaged
+Genesis discovery plugin. Its `SessionStart` hook executes before the first
+user prompt. In a nonempty Git repository without `genesis/blueprint.md`, it
+injects an instruction that the first assistant reply strongly recommend
+`genesis adopt`. It does not perform adoption automatically. If the user
+accepts, Codex can run the command and follow its returned prompt in the same
+conversation. Other hosts can call `adoptProject()` and send its `prompt`
+directly.
+
+Codex can instead use the project-local hooks installed by `genesis init`.
+Those hooks inject a short operating guide, record whether the current turn
+changed project files, then request two bounded continuations: first reconcile
+Blueprint and affected Program explanations from the Git-visible changes, then
+Deslop the implementation. They invoke the same Genesis project operations and
+never start another agent process. A per-session phase permits only
+`implementation -> reconcile -> deslop -> done`. Genesis refreshes both City
+projections after reconciliation so Deslop sees the current explanation and
+function inventory, then refreshes them again after Deslop in case cleanup
+changed the implementation map.
+
+Once Codex identifies relevant source, `genesis context <path...>` returns only
+Program modules citing those paths plus concise selected Stack context, the
+functions structurally indexed in those paths, available Agent Skill catalog,
+and verification commands. `genesis index <name-or-path>` searches the complete
+current function inventory and refreshes `.genesis/machine-city.json` and
+`.genesis/program-city.json`. No model call or semantic subsystem guess is
+involved.
+
+`genesis init` installs the three Genesis workflow skills under
+`.agents/skills/`. `genesis stack add` also installs any complete authoritative
+Agent Skill directory declared by selected components. Generated prompts name
+matching `SKILL.md` entrypoints rather than eagerly embedding their references.
+This follows Agent Skills progressive disclosure and keeps official or
+user-installed generic technology skills independent.
+
+Matching files under `genesis/stack/<component>.md` may add to or override that
+selected component's Description, Guidance, and Deslop fields. Effective
+Guidance is used by work, review, Program, describe, Deslop, and path-context
+generation. The Codex continuation flow also carries it into reconciliation and
+cleanup; effective Deslop guidance remains cleanup-only.