genesis-compiler 1.0.0 → 1.2.0

package/docs/stack-components.md

@@ -0,0 +1,304 @@
+# Stack components
+
+Genesis core knows no framework, language, database, package manager, or
+environment-variable name. A built-in component is one Markdown file at
+`stacks/pieces/<id>.md`.
+
+````markdown
+# Stack piece: example
+
+## Description
+
+What this component contributes.
+
+## Requires
+
+- `nodejs`
+
+## Skill
+
+- Package: `@example/agent-docs`
+- Path: `skills/example`
+
+## Indexers
+
+- `javascript`
+
+## Resources
+
+```json genesis-resource
+{
+  "id": "service",
+  "environmentAlternatives": [
+    { "required": ["SERVICE_URL"] },
+    { "required": ["SERVICE_HOST", "SERVICE_PORT"] }
+  ]
+}
+```
+
+## Guidance
+
+### Technology-specific behavior
+
+- 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`
+- Prepare `Install web dependencies` with `nodejs` in `web`: `npm` `install`
+
+## Deslop
+
+- Concise technology-specific cleanup guidance.
+
+## Commands
+
+- Verify `tests`: `npm` `test`
+
+## Launch
+
+### Target `app`: Run app
+
+- Default.
+- Workdir: `.`
+- Preferred port: `3000`
+- URL path: `/`
+- Runtimes: `nodejs`
+- Prepare `Build`: `npm` `run` `build`
+- Serve `Start`: `npm` `run` `server` `--` `--host` `{host}` `--port` `{port}`
+
+#### Preview identity
+
+- Command: `.vibe64/bin/preview-identity`
+- Protocol: `vibe64.preview-identity.command.v1`
+- Identity types: `email` `login` `user-id`
+- Enabled environment: `APP_PREVIEW_IDENTITY_ENABLED`
+- Secret environment: `APP_PREVIEW_IDENTITY_SECRET`
+- Runtimes: `nodejs`
+- Timeout ms: `10000`
+````
+
+`Description` and `Requires` are the only required sections. `Requires` forms
+dependency closure. Optional `Conflicts` uses the same list format. `Skill`
+selects one complete [Agent Skills](https://agentskills.io) directory, either
+from Genesis or from the declared npm package. Its `SKILL.md`, `references/`,
+`scripts/`, `assets/`, and `agents/` metadata are copied together to
+`.agents/skills/<skill-name>/`; the agent loads them progressively instead of
+Genesis expanding every manual into every prompt. `Resources` declares generic
+alternative environment-name sets reported by prompt generation and checked
+before verification. `allowEmpty` may name a required variable whose empty
+string is valid. `Guidance` is supplemental prose used by work, review, Program,
+description, and cleanup prompts, as well as path-focused context. `Deslop`
+adds cleanup-only prose to explicit cleanup and the automatic Codex cleanup
+continuation. With no selected component, only the `genesis-deslop` skill
+applies. `Commands` accepts only argument-safe `Verify` entries and runs only
+through `genesis verify`.
+
+`Workspace setup` is an optional exact, ordered recipe for a host preparing a
+fresh workspace. Each entry uses this readable, shell-free form:
+
+```markdown
+- 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. 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`
+therefore declare no installer; a concrete piece such as `jskit` may declare
+one.
+
+Precedence is intentionally small and deterministic:
+
+1. A project `## Workspace setup` section in `genesis/stack.md` replaces every
+   selected component default.
+2. Without a project section, exactly one selected component recipe is used.
+3. With no declaration the result is `unconfigured`; with several component
+   recipes it is `blocked` as ambiguous. Genesis never merges them.
+
+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,
+Preferred port, URL path, and Runtimes are optional; their normalized defaults
+are false, `.`, null, `/`, and no runtime requirements. Every Prepare or Serve
+command and argument is a separate backticked value returned as an `argv`
+array, never a shell program. A target has exactly one final Serve step; any
+earlier steps must be Prepare steps. Workdir is canonical and project-relative,
+Preferred port is only a hint from 1024 through 65535, and URL path is an
+application path rather than a URL. The only substitutions are `{host}` and
+`{port}`, supplied by the host. A project can use `- Nothing.` as its complete
+Launch section to disable component targets.
+
+Genesis validates and reports Launch data but does not select a runtime,
+reserve a port, start a process, decide readiness, or control a browser.
+
+The optional `#### Preview identity` block is specific to hosts that implement
+the declared `vibe64.preview-identity.command.v1` protocol. Its executable is a
+committed, application-owned file immediately below `.vibe64/bin`; the
+normalized command is an argv array, not a shell program. Identity types may
+contain `email`, `login`, and `user-id`. Enabled environment and Secret
+environment are optional variable
+names the application recognizes; Genesis validates and returns names only and
+never reads or returns their values. Runtimes lists opaque runtimes required
+to execute this command, independently of the server target requirements, and
+Timeout ms defaults to 10000 with a maximum of 30000. Genesis does not execute
+the command, select identities, provide secrets, authenticate users, or control
+the browser. Those remain host responsibilities.
+
+`runtimeRequirements` contains opaque technology ids. A host explicitly maps
+the ids it supports to its own pinned runtime packs; for example, it may map
+`nodejs` to its Node 26 pack. Genesis never chooses versions, expands
+dependencies such as `composer`, or treats an unknown id as something similar.
+Declare each independently required runtime. Generic language pieces such as
+`nodejs` and `php` provide no Launch recipe. A concrete piece such as `jskit`
+may declare one; Genesis does not invent missing targets.
+
+`Indexers` selects installed structural adapters for the derived Machine City.
+The shared ast-grep engine owns traversal, bounds, diagnostics, JSON, and
+queries; each adapter owns only language extensions, callable syntax, names,
+containers, signatures, and public/internal visibility. Several Stack pieces
+may contribute indexers, and duplicates are collapsed. Index output is
+navigation data, not proof that every dynamic callable or framework edge was
+discovered.
+
+Do not create a Genesis-owned generic skill merely because a component is
+named `nodejs`, `php`, or another common technology. Official, user, and host
+skills with those names must coexist normally. Use `## Skill` only for an
+authoritative directory this Stack component selects; put concise supplemental
+rules in `## Guidance` and cleanup-only additions in `## Deslop`.
+
+A selected component may have one project customization at
+`genesis/stack/<id>.md`:
+
+```markdown
+# Stack customization: example
+
+## Add
+
+### Description
+
+Additional project context.
+
+### Guidance
+
+- Additional implementation, explanation, review, and cleanup guidance.
+
+### Deslop
+
+- Additional cleanup guidance.
+
+## Override
+
+### Description
+
+Replacement component description.
+
+### Guidance
+
+- Replacement installed general guidance.
+
+### Deslop
+
+- Replacement cleanup guidance.
+```
+
+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, 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
+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, 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:
+
+```js
+import { inspectWorkspaceSetup } from 'genesis-compiler';
+
+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`, `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.
+
+Preview hosts read the normalized Launch contract independently:
+
+```js
+import { inspectLaunch } from 'genesis-compiler';
+
+const launch = await inspectLaunch({ projectRoot, environment });
+```
+
+The result has `status` (`ready`, `blocked`, or `unconfigured`), `stackHash`,
+selected `components`, distinct `runtimeRequirements`, declared `resources`,
+normalized `targets`, and resource `diagnostics`. Each target reports its
+`source`, `available`, and `disabledReason`, plus its normalized
+`previewIdentity` declaration when present. Environment values are inspected
+but never returned. Here, `available` means only that the Stack's declared
+resource inputs are present: the host must still reject runtime requirements it
+cannot map. `unconfigured` means there are no targets, `blocked` means declared
+resource inputs are missing, and `ready` means neither condition applies. The
+caller still owns exact runtimes, port allocation, process lifecycle, readiness
+and proxy policy, identity selection and command execution, secrets, browser
+binaries, Git, and credentials.

package/package.json

@@ -1,12 +1,62 @@
 {
   "name": "genesis-compiler",
-  "version": "1.0.0",
-  "description": "",
-  "license": "ISC",
-  "author": "",
-  "type": "commonjs",
-  "main": "index.js",
+  "version": "1.2.0",
+  "type": "module",
+  "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with optional Codex hooks.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mobily-enterprises/genesis-compiler.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mobily-enterprises/genesis-compiler/issues"
+  },
+  "homepage": "https://github.com/mobily-enterprises/genesis-compiler#readme",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "genesis": "bin/genesis.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./cli": "./src/cli.js"
+  },
+  "files": [
+    ".agents/plugins/marketplace.json",
+    "bin",
+    "docs/assurance-model.md",
+    "docs/stack-components.md",
+    "docs/prompt-integration.md",
+    "prompts/blueprint.txt",
+    "prompts/describe.txt",
+    "prompts/deslop.txt",
+    "prompts/program.txt",
+    "prompts/reconcile.txt",
+    "prompts/review.txt",
+    "prompts/start.txt",
+    "prompts/work.txt",
+    "plugins/genesis",
+    "skills",
+    "src",
+    "stacks/pieces"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@ast-grep/lang-bash": "^0.0.8",
+    "@ast-grep/lang-c": "^0.0.6",
+    "@ast-grep/lang-cpp": "^0.0.6",
+    "@ast-grep/lang-csharp": "^0.0.6",
+    "@ast-grep/lang-go": "^0.0.6",
+    "@ast-grep/lang-java": "^0.0.7",
+    "@ast-grep/lang-kotlin": "^0.0.7",
+    "@ast-grep/lang-php": "^0.0.7",
+    "@ast-grep/lang-python": "^0.0.6",
+    "@ast-grep/lang-ruby": "^0.0.7",
+    "@ast-grep/lang-rust": "^0.0.7",
+    "@ast-grep/napi": "^0.45.1",
+    "@jskit-ai/agent-docs": "0.1.131",
+    "yaml": "^2.9.0"
   }
 }

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

@@ -0,0 +1,19 @@
+{
+  "name": "genesis",
+  "version": "1.2.0",
+  "description": "Makes Codex aware of optional Genesis adoption for existing projects.",
+  "author": {
+    "name": "Mobily Enterprises"
+  },
+  "interface": {
+    "displayName": "Genesis",
+    "shortDescription": "Discover and adopt Genesis project explanations.",
+    "longDescription": "Recommends the optional Genesis explanatory layer when Codex opens an existing project that has not adopted it.",
+    "developerName": "Mobily Enterprises",
+    "category": "Productivity",
+    "capabilities": ["Read"],
+    "defaultPrompt": [
+      "Adopt Genesis in this existing project"
+    ]
+  }
+}

package/plugins/genesis/hooks.json

@@ -0,0 +1,18 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "^(startup|resume)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if command -v genesis >/dev/null 2>&1; then genesis hook discover; fi",
+            "commandWindows": "genesis hook discover",
+            "timeout": 3,
+            "additionalContextLimit": 1200
+          }
+        ]
+      }
+    ]
+  }
+}

package/prompts/blueprint.txt

@@ -0,0 +1,9 @@
+Read and follow `.agents/skills/genesis-program/SKILL.md` completely, operating
+in Blueprint-only mode.
+
+Update `genesis/blueprint.md` from the explicit user intent supplied below.
+Preserve existing intent unless the user changes it. Edit no other file. Do not
+infer product requirements from accidental implementation behavior. Keep one
+short, cohesive, non-technical Blueprint rather than a change log.
+
+When finished, summarize the intent that changed.

package/prompts/describe.txt

@@ -0,0 +1,17 @@
+Read and follow `.agents/skills/genesis-program/SKILL.md` completely, operating
+in initial-description mode.
+
+Create or refresh the complete explanatory Blueprint and useful Program for the
+codebase that exists now. Read implementation, tests, user-facing documentation,
+current Blueprint, and current Program. Prefer explicit user guidance; otherwise
+infer conservatively from observable behavior supported by code and tests.
+Use Machine City as a navigation aid when available, but verify relevant source
+directly rather than treating the derived index as authority.
+
+If the codebase is too large for one careful pass, use subagents as you judge
+appropriate, reconcile their findings, and remain responsible for one coherent
+result. Identify anything not inspected or genuinely uncertain.
+
+Edit only `genesis/blueprint.md` and explanatory Markdown below
+`genesis/program/`. Summarize every explanatory file created, updated, or
+removed.

package/prompts/deslop.txt

@@ -0,0 +1,14 @@
+Read and follow `.agents/skills/genesis-deslop/SKILL.md` completely.
+
+This is a dedicated behavior-preserving cleanup task, separate from
+implementation. Review the requested scope, or otherwise the ordinary Git diff
+and immediately related code. Apply every selected Stack cleanup instruction
+supplied below and load applicable official technology skills for additional
+language and framework context.
+
+Use `.genesis/machine-city.json` and `genesis index <name-or-path>` to find
+existing public and internal functions. Remove or consolidate genuine repeated
+helpers, but confirm behavior and call sites in source before changing them.
+
+Do not broaden the product change. Run focused checks when useful and summarize
+what became simpler, files changed, and checks actually run.

package/prompts/program.txt

@@ -0,0 +1,12 @@
+Read and follow `.agents/skills/genesis-program/SKILL.md` completely, operating
+in complete Program-refresh mode.
+
+Explain the code that currently exists using the smallest useful
+subsystem-oriented Program. Read implementation, tests, Blueprint, and current
+Program material. Use Machine City as a navigation aid, then verify relevant
+source directly. Edit only explanatory Markdown below `genesis/program/`.
+Delete stale or duplicate modules and do not edit code, tests, configuration,
+Blueprint, Stack, or `.genesis/`.
+
+When finished, summarize Program files created, updated, or removed and report
+genuine ambiguity.

package/prompts/reconcile.txt

@@ -0,0 +1,12 @@
+Read and follow `.agents/skills/genesis-program/SKILL.md` completely, operating
+in focused post-change reconciliation mode.
+
+Use the preceding implementation turn, listed changed paths, actual Git diff or
+history, and relevant tests. Update Blueprint only for intentional observable
+product behavior. Update only affected Program modules. Private restructuring
+may require only Sources or an informational Implementation map, and may require
+no explanatory edit at all.
+
+Do not simplify or edit implementation, tests, configuration, dependencies,
+Stack, or `.genesis/` during this turn. Do not run Deslop yet. Summarize every
+explanatory change and genuine ambiguity.

package/prompts/review.txt

@@ -0,0 +1,12 @@
+Read `.agents/skills/genesis-project/SKILL.md` and
+`.agents/skills/genesis-program/SKILL.md` completely, then perform a read-only
+review.
+
+Compare Blueprint intent, observable implementation, tests, Program public
+contracts, informational implementation maps, and recorded verification in both
+directions. Identify missing or contradictory behavior, misleading explanation,
+unnecessarily difficult public shape, and verification gaps. Distinguish direct
+evidence from inference and state questions that require human intent.
+
+Do not edit any file. Return a concise report ordered by impact with exact file
+references, the evidence inspected, and the smallest sensible correction.

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

@@ -0,0 +1,28 @@
+Read and follow `.agents/skills/genesis-project/SKILL.md` completely, then
+implement the request in the ordinary local Git tree.
+
+Load the applicable official or project technology skills listed below. Use
+their normal generators, commands, packages, and established seams. Do not
+search package internals or unrelated manuals merely to reconfirm an exact lane.
+Before adding a helper or public operation, query `genesis index <name-or-path>`
+and reuse an existing function when it already owns the behavior.
+
+This is the implementation turn. Do not edit the Blueprint, Program, or
+`.genesis/`; the separate reconciliation turn owns explanatory changes. Keep an
+exact Stack `## Launch` declaration aligned when the implementation establishes
+or intentionally changes how the project is started or how Vibe64 may request
+an application preview identity. Declare only command paths, protocol, supported
+identity types, environment variable names, runtimes, and timeout policy; never
+put an environment value or secret in Stack. Never invent missing external-resource
+values. Preserve useful work and report a genuinely missing resource instead of
+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/skills/genesis-deslop/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: genesis-deslop
+description: Perform a separate behavior-preserving cleanup pass after implementation. Use when asked to Deslop, simplify, remove repeated helpers, clarify ownership, or align changed code with established project and technology patterns.
+---
+
+# Genesis Deslop
+
+Review and simplify the current local codebase without changing product
+behavior. Start with the requested scope, or otherwise the ordinary Git diff
+and the code immediately around it.
+
+Consult `.genesis/machine-city.json` or run `genesis index <name-or-path>` to
+find existing public and internal functions before introducing or consolidating
+an abstraction. Confirm every apparent duplicate in source and its call sites.
+
+Leave no repeated helpers, no code that is unclear or hard to reason about, no
+obviously wrong code, and no code that goes against best practices or
+established patterns in the codebase. Remove unnecessary wrappers, abandoned
+scaffolding, parallel framework plumbing, and speculative abstractions.
+Consolidate ownership where one clear module is enough. Do not optimize for tiny
+files or indirection; optimize for a small, obvious design that a junior
+programmer can follow.
+
+Apply every technology-specific Deslop instruction supplied by the selected
+Stack. Load applicable official technology skills for additional framework and
+language context, but do not expect them to contain Genesis's cleanup policy.
+
+You may edit or delete implementation and test files when that is the clearest
+behavior-preserving cleanup. Do not edit `genesis/`, `.genesis/`, Git metadata,
+dependency directories, generated build output, retained migration history, or
+external resources. Do not weaken tests, public behavior, or data guarantees.
+Do not create a second architecture or perform unrelated rewrites.
+
+Run focused checks when useful. Final declared checks remain available through
+`genesis verify`. Summarize what became simpler, files changed, and checks
+actually run.

package/skills/genesis-deslop/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Genesis Deslop"
+  short_description: "Simplify changed code without behavior drift"
+  default_prompt: "Use $genesis-deslop for a separate behavior-preserving cleanup pass over the current changes."

package/skills/genesis-program/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: genesis-program
+description: Create, reconcile, or review the explanatory Blueprint and subsystem-oriented Program of a Genesis project. Use when adopting a codebase, documenting public operations, or updating explanations after implementation changes.
+---
+
+# Genesis Blueprint and Program
+
+Blueprint and Program are maintained explanations, not proof, ownership, or an
+exhaustive semantic model.
+
+## Blueprint
+
+`genesis/blueprint.md` is a short, cohesive, non-technical description of what
+the product should do. Prefer explicit user intent. Do not mention frameworks,
+packages, route spellings, schemas, source files, implementation plans, tests,
+or private architecture.
+
+Update Blueprint after implementation only when the change intentionally adds,
+removes, or alters observable product behavior. Never turn an accident, bug,
+private design choice, or ambiguity into product intent.
+
+## Program
+
+Organize Program beneath conceptual subsystem directories:
+
+```text
+genesis/program/billing/invoices.md
+genesis/program/authentication/sessions.md
+```
+
+Create one module for each meaningful public operation provided by a subsystem,
+regardless of language or source layout. Public operations include exported
+functions or methods, API actions, commands, UI operations, and other observable
+entry points. Do not mirror source files or document every helper.
+
+Each module contains:
+
+```markdown
+# Human-readable boundary name
+
+One short explanation of why the boundary exists.
+
+## Sources
+
+- `exact/authored/source/path`
+
+## Public contract
+
+Meaningful inputs, outputs, effects, failures, and guarantees.
+```
+
+An optional `## Implementation map` may name only private helpers or seams that
+materially help a future agent change, trace, or debug the operation. It is
+informational, not a public guarantee. Tests are evidence and never
+implementation Sources.
+
+Prefer fewer, clearer modules. Remove stale and duplicate explanations. A
+source may support several operations; helper and glue files may appear in no
+Program module.
+
+## Task boundaries
+
+The caller determines whether this is initial description, complete Program
+refresh, focused post-change reconciliation, Blueprint-only work, or read-only
+review. Respect the caller's edit boundary. Report ambiguity rather than
+inventing intent.