Self Evolve

Self-Evolve

Run at the end of a project to promote what worked in this project into framework-level priors. Future projects then start ahead because vibegame init ships the priors.

Workflow

The orchestrator coordinates this workflow and owns code and architecture outputs (modules, skeletons, and contracts excluding the Artist chapter). Skeleton-specific errors belong inside the matching skeleton. Art-recipe distillation belongs to artist via the artist-self-evolve skill — dispatch it in parallel.

0. Self Check. Before promoting or syncing a skeleton, audit the finished project itself. The project will become a future starting point, so fix these issues in the project before opening a task to convert it into skeletons/<slug>/:

   • Engine-owned runtime facts stay engine-owned. Anything the engine can express — especially visual scale, width / height, offset, pivot, depth, collider width / height, collider offset, collider pivot, scroll factor, animation clip timing, and similar runtime visual / collision behavior — must be declared in scene JSON, node JSON, manifest metadata, or config that the engine reads. Do not bypass the engine by setting visual scale / offset / pivot or collider scale / offset / pivot imperatively in scripts when an engine parameter exists.
   • No unexplained hard-coded numbers. Gameplay, physics, visual sizing, hitbox dimensions, spawn timing, camera bounds, UI placement, and animation timing must come from scene JSON, node JSON, manifest metadata, or config. Numeric constants in scripts are allowed only for local math identities or tiny implementation defaults that are not game tuning; otherwise move them to config before evolve.
   • Single-node config stays inline. If a config value only applies to one node instance, put it in that node's inline config in the scene / node JSON. Create config/*.json only for shared tuning used by multiple nodes, reusable rosters/tables, large state machines, or values intentionally edited as a named subsystem.

   If any of the above fail, stop the evolve run, fix the project, and re-test before continuing. Do not record a skeleton that depends on script-side overrides to compensate for missing engine parameters.

1. Dispatch art-side evolve. At the start of the run, send the persistent artist teammate this minimal message:

   game-slug: <slug>
   Use your `artist-self-evolve` skill for this run.

   Artist runs the skill and:

   • Writes skeletons/<slug>/art-pack.md directly (Phase 1) — sub-genre-bound, no gate.
   • Stands by for per-contract #### Artist chapter requests from you in Step 5 (Phase 2).

   The art-pack is part of the skeleton output. Contract Artist chapters are part of the approved contract output.

   If artist replies that the skill is unavailable (harness doesn't expose it), abort the evolve run and report to user. Running self-evolve without art-side coverage leaves art-pack.md empty and contracts' Artist chapters uncovered.

2. Search for candidates per destination, independently. Run the skeleton / modules / contracts searches in parallel. Do not "find candidates first, then classify". Each target's search rule and qualification bar lives in Evolve Targets. Search reusable failure modes while evaluating skeletons; they are part of the skeleton update, not a separate destination.

3. Present each list to the user and wait for approval. Show one list per destination: skeletons / modules / contracts. Include skeleton-owned error notes under the relevant skeleton item, not as a fourth list. Do not force a unified table; each list's shape can fit its content. The user may merge / split / drop items — accept their direction. This gate is about which priors get touched, not their content. Lifting priors silently locks in framework defaults for every future project, so this gate is non-negotiable.

4. Convert approved skeletons via task workflow. For each approved skeleton candidate, open a task whose prd.md explicitly requires converting the finished project into a runnable placeholder skeleton under skeletons/<slug>/. Do not hand-convert the skeleton inside the orchestrator session; let the task workflow produce and verify it. Use the PRD requirements and review bar in Evolve Targets / skeletons.

5. Draft contracts, delegate the Artist chapter. When you write a contract (new file or new Pattern), author the structure and every non-Artist responsibility chapter (#### Architect/Programmer, #### Player, #### Reviewer, optional ### Manifest and asset boundary). Then send artist a per-contract request with the file path and the surrounding pattern context; artist writes #### Artist (and its nested ##### Workflow) directly into that file (Phase 2). Do not have artist return a draft for you to relay — chapter content is artist's domain.

6. Verify. Run vibegame check from the project root; resolve naming / structural failures before promotion.

7. Promote through the CLI. Run one command for each user-approved prior:

   vibegame evolve skeleton -n <kebab-case-slug> --dry-run
   vibegame evolve module -n <PascalCaseModule> --dry-run
   vibegame evolve contract -n <kebab-case-slug> --dry-run

   Review the copied files and not copied lists. After the dry run passes, rerun without --dry-run. The CLI finds the VibeGame source checkout from its installed code and writes only to the fixed destination for that prior type. Do not use cp, rsync, or manual whole-directory copying to promote shared priors. The CLI never commits or pushes.

   If a destination exists, stop. Compare and resolve the conflict manually; the CLI does not replace or merge existing priors.

8. Update the source index manually. After a successful promotion, the CLI prints the absolute path of the source index that requires a manual edit. Do not infer the source checkout path from the game project. If the printed path is outside the current game project, obtain user permission to edit it, then update that exact file. The CLI never copies or edits an index.

Global Rules

• Project specifics never leak into priors — no character names, no PvP-vs-PvE assumptions, no "current KOF" snapshots. Use neutral identifiers (p1 / p2, fighter, bar).
• Framework-shared outputs must be reproducible from the shipped repo alone. Shared outputs are files under modules/, skeletons/, .vibegame/spec/contracts/, and .vibegame/spec/engine/. Other project files are not shared priors.
• No absolute paths, seed-project references, private worktree paths, or project-specific file references in shared outputs. Do not cite REFLECTION.md, plan.md, log.md, screenshots, prompt artifacts, or other source-project files as if future projects can read them. Distill the lesson into the shared file instead.
• Do not refer to a "seed project", "source project", "current project", "sibling project", "attached image", or "user-provided file" from a shared output. If a reference image is required, ship it explicitly under skeletons/<slug>/art-pack-assets/ and refer to that relative path.
• art-pack.md records the verified generation method and useful candidate outputs. assets/manifest.json records only assets selected by the runtime. Generated but unused assets do not belong in the runtime manifest; remove their entries and runtime files before promotion.
• Skeleton promotion copies only the standard skeleton files: root project.json, index.html, index.md, art-pack.md, and errors.md; JSON under config/; *.scene.json under scenes/; *.node.json under entities/; JavaScript under scripts/; reference images under art-pack-assets/; and manifest-selected files under assets/. It does not copy project-local engine/, modules/, stages/, vendor/, .vibegame/, tests/, or any other unlisted content.
• Modules are promoted independently through vibegame evolve module. Never place or copy a modules/ directory inside a skeleton.
• Ship only what was load-bearing in a real task. Do not invent priors that were never used.
• Your job is to let future orchestrators choose, not to force a choice. Keep ### When to use grounded in verified capability, not plausible genre extrapolation.
• Modules / contracts qualification: extract only when the pattern is plausibly reusable in other sub-genres OR is a standard part of every project in the same sub-genre. One-off conveniences stay in the project.
• Modules require real encapsulation, not copy-and-rename. Promote scripts/X.js only after refactoring it into a properly parameterized module — all tunables flow through this.config, no hard-coded project assumptions, public methods are documented at the top of the file. If it cannot be cleanly encapsulated, it does not qualify.
• Contracts and modules are independent evolve targets:
  • Extract a contract when a recurring feature needs a special cross-role production workflow that the ordinary task workflow does not express. Its implementation may use engine APIs, an existing module, a new module, or project-owned code.
  • Extract a module when a real project has proved a reusable, encapsulated runtime behavior. Do not create a module only because a contract includes programming work.
  • When a verified module implements part of a contract, reference it from the relevant responsibility chapter. The contract owns the cross-role workflow; the module source owns its code interface.
  • A module with no cross-role concerns does not need a contract. Document its purpose, config fields, public methods, and minimal usage in its source header.

Evolve Targets

modules

Scan scripts/ and current modules/ usage for code that passes the qualification gates. List each as scripts/<X>.js, scripts/<Y>.js (if multiple scripts merge into one module) => modules/<X>Module.js with one sentence describing what the module achieves. Every promoted module must also gain a row in modules/index.md with one line description and one line interface.

How to choose functionality for module extraction

Prioritize functionality that:

• Owns frontend rendering effects that users accepted.
• Couples assets, collision, and behavior into one runtime unit.

Pure gameplay logic is usually easy to rewrite correctly. Code that affects visuals and real runtime feel is easier to get subtly wrong and harder to test, so it is more valuable to preserve as a module.

How to turn project logic into a module

Step 1: Define the module behavior

A well-encapsulated module is used through these surfaces:

1. xxx.node.json: script: "XxxModule" turns the module into a node that works once placed in scene.json through normal lifecycle methods such as ready and update. Store all tunables in config; reuse engine-native fields such as animator, visual, and collider for animation and collision.
2. manifest.json: records the asset keys the module needs.
3. Project code: wires the module interface into game logic. A module often detects and emits events; project code consumes those events for damage, story, scoring, or other project-specific outcomes.

A module must have a clear behavior boundary. Other scripts should only provide inputs, consume outputs/events, or read public state; they must not maintain the module's core behavior. The module should work by itself. If it is coupled to another object, either split the coupling and expose that object's data/methods as module inputs, optionally through parent/child nodes, or turn the other object into a module too.

Define the module's configuration and behavior before moving code.

Step 2: Modularize the project

Move the relevant functionality into modules/, change the original node reference to XxxModule, then implement the module according to the behavior boundary defined in Step 1.

Step 3: Test

The module implementation is acceptable only after a real project proves that the module works correctly.

Step 4: Self-check

When possible, implement module self-check logic callable through vibegame check xxx.node.json. check detects module nodes and calls the matching module check code. This is especially useful for:

• Errors that can be found before runtime, such as missing required config keys.
• Multi-structure consistency, such as collider alignment against animation frame size and position. If it cannot be fully asserted, output review images; this is easier than detecting it at runtime.

Self-check code schema

Module self-check has two layers:

1. Runtime self-check: lives in modules/XxxModule.js and catches runtime configuration errors.
2. Static module check: lives in modules/check/XxxModule.check.py and is auto-discovered by vibegame check xxx.node.json.

Runtime self-check

Runtime self-check uses _selfCheck() and usually runs from ready().

Use it to:

• Check objects that only exist at runtime: physics body, animator instance, child node instances, tag query results.
• Emit clear console.error / console.warn messages.
• Avoid generating images. This does not replace vibegame check.

Minimal shape:

ready() {
  this._selfCheck()
}

_selfCheck() {
  const tag = `XxxModule[${this.name}]`
  const errors = []
  const warns = []

  if (!this.animator) errors.push('node.json must define animator')
  if (!this.getPhysicsObject?.()?.body) errors.push('node.json must define collider')
  if (!this.config.requiredKey) errors.push('config.requiredKey is required')

  for (const e of errors) console.error(`${tag}: ${e}`)
  for (const w of warns) console.warn(`${tag}: ${w}`)
  if (!errors.length && !warns.length) console.log(`${tag}: self-check passed`)
}

Static module check

Static module check is the preferred self-check path. The file name must match the module script:

modules/XxxModule.js
modules/check/XxxModule.check.py

vibegame check discovery rules:

• The node declares "script": "XxxModule".
• vibegame check entities/foo.node.json looks for modules/check/XxxModule.check.py.
• Whole-project vibegame check . scans all *.node.json files and calls matching .check.py files for *Module nodes.
• The check file exposes check(project: Path, node_path: Path, opts: dict | None = None) -> list[str].
• Message prefixes determine report level: ERROR, WARN, PREVIEW, PASS.

Minimal shape:

import json
from pathlib import Path


def check(project: Path, node_path: Path, opts: dict | None = None) -> list[str]:
    opts = opts or {}
    messages: list[str] = []
    node = json.loads(node_path.read_text())

    config = node.get("config") if isinstance(node.get("config"), dict) else {}
    animator = node.get("animator") if isinstance(node.get("animator"), dict) else {}
    children = {
        child.get("name")
        for child in node.get("children", [])
        if isinstance(child, dict) and isinstance(child.get("name"), str)
    }

    if not config.get("requiredKey"):
        messages.append("ERROR config.requiredKey: required")
    if "Hitbox" not in children:
        messages.append('WARN child "Hitbox" not found')
    if "idle" not in animator.get("states", {}):
        messages.append('ERROR animator.states.idle: required')

    if not any(m.startswith("ERROR") for m in messages):
        messages.insert(0, "PASS static check passed")
    return messages