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

genesis/
  blueprint.md       non-technical product intent
  stack.md           selected technology guidance, verification, declarations, and opaque extensions
  stack/             optional per-component Description, Guidance, Adoption, 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:

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.

Install the framework-neutral compiler and the optional first-party technology catalog as separate packages:

npm install --global genesis-compiler genesis-stack

genesis-compiler has no dependency on genesis-stack or on any framework. The catalog is static Markdown and contains the complete curated set of language, database, UI, and framework pieces. A host may supply another catalog through the same contract.

For an existing codebase, adopt is the direct entry point:

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 adopt prompt. That prompt imports the existing application's factual Stack declarations—including environment/resources, verification, and consumer-owned opaque sections—then creates the first useful Blueprint and Program. Give it to the agent already working in the repository. Adoption edits Genesis metadata only; implementation modernization remains a separate, explicitly approved port. “Adopt” never moves the project.

For a new or empty project, initialize first and write the product intent:

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:

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 asks the assistant to recommend preparing the existing project for guided editing in product language. Codex cannot display an ordinary assistant reply until the user speaks, so the recommendation appears in its first reply. If approved, the assistant runs genesis adopt; the person need not know Genesis terminology or type a command. 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: 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:

genesis stack add --stack-package genesis-stack nodejs
# or: genesis stack add --stack-package genesis-stack 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. Every relative Markdown link and image 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. For example, the genesis-stack catalog's 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 manage project environments can call inspectEnvironment(). Concrete Stack integrations may declare public, non-secret Environment defaults such as the database driver selected by that integration. Explicit host or user values take precedence. The catalog's JSKIT MySQL and PostgreSQL pieces respectively declare DB_CLIENT=mysql2 and DB_CLIENT=pg, so users provide connection values rather than restating a deterministic technology choice. A project may instead declare complete ## Resources and ## Environment defaults sections in genesis/stack.md; their presence replaces component declarations so an imported C++, PHP, Python, or older application keeps its own real names and public constants. 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 public defaults, resource declarations, value-free missing-input diagnostics, and paths. It never returns supplied environment values, writes files, stores secrets, or decides which resolved host values should be materialized.

Consumers may define additional ## sections in a project or component Stack. Genesis composes each section by name, includes its exact text in Stack identity and prompt context, and exposes it through inspectStackSection(). The body is opaque: Genesis does not parse its commands, infer its purpose, or execute it. A project section replaces a component default of the same name; competing component declarations are reported mechanically instead of merged.

This is the boundary for every consumer-specific operation. The consumer that names a section owns its schema, validation, runtime mapping, execution, and proof of success. Genesis has no model of starting, preparing, deploying, packaging, migrating, serving, probing, or supervising a project. A web host, native toolchain, firmware publisher, desktop signer, or any future consumer can define different sections without a Genesis compiler change.

Standalone and non-Node hosts can inspect these same normalized contracts without importing the JavaScript API or parsing Markdown:

genesis inspect environment --json
genesis inspect section 'Consumer operation' --json

Without --json, the commands print concise human-readable summaries. They never interpret or execute a consumer-owned section.

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:

genesis context src/path/to/file

Before introducing another helper or public operation, query the current function inventory:

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 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:

# 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:

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:

genesis prompt "Add filtering by note title"

Prompt tasks

genesis prompt                                      # implementation work
genesis prompt --task start                        # open a new or existing project conversation
genesis prompt --task adopt                        # import an existing project's complete contract
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 eight 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.
• 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.
• 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 pieces from the installed optional catalog:

genesis stack list --stack-package genesis-stack
genesis stack add --stack-package genesis-stack jskit jskit-mysql

The explicit package flag bootstraps an unconfigured project. Once a Stack selection records genesis-stack in genesis/stack.md, ordinary commands use that recorded package directly; genesis stack list needs no host flag.

genesis/stack.md records the owning Stack package, component ids, and optional project verification commands. After the first selection, ordinary commands resolve the recorded package without another flag. Selecting no components is valid. genesis-stack contains the eleven common language families listed above, plus Vue, MySQL, PostgreSQL, JSKIT, and JSKIT database integrations. Components may contribute:

• a concise description and supplemental Guidance used across relevant tasks;
• existing-project Adoption requirements used only while importing a codebase;
• 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; Adoption adds import-only requirements; Deslop adds cleanup-only rules. 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 platform dependency. See Stack components.

Verification

Run the Stack's declared checks explicitly:

genesis verify

Genesis applies public Stack defaults beneath explicit environment values, evaluates generic resource declarations, and runs each declared Verification 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, Adoption, 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:

## Verification

- Verify `tests`: `npm` `test`
- Verify `build`: `npm` `run` `build`

Inspection

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;
• environment declarations and consumer-owned Stack extensions as ready, blocked, or honestly unconfigured;
• 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

import {
  adoptProject,
  addStack,
  check,
  generatePrompt,
  getContext,
  indexCodebase,
  initialize,
  inspectEnvironment,
  inspectStackSection,
  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 adopt 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. inspectEnvironment() returns normalized Stack resource declarations, public non-secret defaults, value-free missing-input diagnostics, and dotenv projection paths without returning any supplied environment value. inspectStackSection() returns one exact consumer-owned section without interpreting or executing its contents.

Normalized results identify their stable public contract in the contract field: genesis.environment.v1, genesis.stack-section.v1, or genesis.verification.v1. A consumer defines any schema embedded inside the opaque section body.

A host such as Vibe64 can send the generated prompt to its existing agent:

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.