--- name: Self-Evolve slug: self-evolve category: AI Engineering description: Self-Evolve captures patterns from a finished project and promotes them into framework-level priors for future runs. Use it only when explicitly doing a self-evolution pass after a project is complete. github: "https://github.com/tettethu/VibeGame/tree/main/src/skills/self-evolve" language: Python stars: 200 forks: 11 install: "npx degit https://github.com/tettethu/VibeGame/tree/main/src/skills/self-evolve ~/.claude/skills/self-evolve" installs_to: ~/.claude/skills/self-evolve source_path: src/skills/self-evolve/SKILL.md collection_size: 5 category_size: 3101 collection_url: "https://dirskills.com/collections/tettethu/VibeGame" added: 2026-09-05T05:31:04.955Z last_synced: 2026-09-05T05:31:04.955Z canonical_url: "https://dirskills.com/skills/self-evolve" --- # Self-Evolve Self-Evolve captures patterns from a finished project and promotes them into framework-level priors for future runs. Use it only when explicitly doing a self-evolution pass after a project is complete. **Install:** ```bash npx degit https://github.com/tettethu/VibeGame/tree/main/src/skills/self-evolve ~/.claude/skills/self-evolve ``` ## README # 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//`: - **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: Use your `artist-self-evolve` skill for this run. ``` Artist runs the skill and: - **Writes `skeletons//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//`. 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: ```sh vibegame evolve skeleton -n --dry-run vibegame evolve module -n --dry-run vibegame evolve contract -n --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//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/.js, scripts/.js (if multiple scripts merge into one module) => modules/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: ```js 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: ```text 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: ```py 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 ``` #### What to assert Assert anything that can be asserted directly. Do not generate an image and make reviewers guess. - Required `config` keys. - Manifest key existence. - Animator state / parameter / clip existence. - Texture / frame existence for animation clip references. - Child node, tag, hitbox name, and action name existence. - Missing or invalid collider / visual / sensor / body fields. - Cross-structure references, such as `config.actions[*].state` pointing to an existing animator state, and `config.actions[*].fx` pointing to an existing child node. #### What to preview For anything requiring visual review, generate `PREVIEW` images instead of describing the issue in text. Default output: ```text assets/artifacts/module-check/ ``` Good preview targets: - Sprite visual and collider alignment. - Animation frame strip and active-frame correctness. - Whether attack / hurt / sensor hitboxes cover the correct frames and body regions. - Whether module-owned DOM / canvas / Phaser visuals match configured size, pivot, and offset. #### Preview coordinate rule Preview must reproduce real runtime coordinate logic. Otherwise the image misleads the reviewer. If the module's visual behavior relies on the engine, preview must use the same rules as engine `visual` / `collider` / `animator`: - Visual source size comes from manifest sprite bbox or image size. - Display size comes from engine fields such as `visual.ratio`, `visual.width`, and `visual.height`. - Collider size / offset / pivot come from node `collider`, including engine default pivot inheritance. - Child hitbox placement uses the same parent/child, pivot, offset, and scale conversion as runtime. - Animation preview uses the real `animations.clips[*].frames` order, and active frames use the real frame indexes from module config. If the module defines its own visual behavior, preview must reproduce the module's own coordinate logic: - Use the real anchor / origin / pivot rules from the module code. - Use the real scale / layout / clipping / mask rules from the module code. - Use the real event active window / hit test rules from the module code. Do not write approximate coordinates just to make preview easier. If the preview cannot reproduce the real behavior, emit a `WARN` explaining what it does not cover. ### art-side evolve Art-recipe distillation belongs to artist via `artist-self-evolve`. Lead responsibilities: - Dispatch artist at the start with `game-slug`. - Do not write `skeletons//art-pack.md` yourself. - For each contract that needs an Artist chapter, write the non-Artist chapters first, then ask artist to fill `#### Artist` directly in that file. Artist responsibilities: - Write `skeletons//art-pack.md`. - Fill contract `#### Artist` chapters when requested. ### contracts Files under `.vibegame/spec/contracts/` are contracts guiding orchestrator how to delegate jobs to different teammates and how teammates should behave to build some special features. Scan task artifacts (`plan.md` and the `# Auditor` / `# Player` sections of each task's `log.md`, plus `REFLECTION.md`) for cross-role coordination rules not yet captured in any contract. List each as a new/extended contract file or Pattern. **Schema** ``` ## Pattern 1: slug-1 ### When to use ### Basic Knowledge ### Responsibility #### Artist ##### Workflow (MANDATORY when artist has nontrivial work. Exactly three steps: Generate / Package / Verify.) #### Architect/Programmer/Auditor