threejs-game-workflow-control

three.js global workflow control

The 3D world uses an independent nested responsiveContract.renderSpace=world-3d; draft according to theworld viewport SchemaandexamplesV4 runtime evidence verifies camera projection, NDC input, rendering budget, and scene ownership; the 2D fixed design contract is used only for the HUD. Machine contracts cannot replace human visual or actual device acceptance, and summaries do not participate in acceptance.

This Skill is the sole state, risk gate, task scope, and evidence control plane for the ThreeJS project. Ordinary tasks are based directly on the current user instructions; domain Skills can iterate within the Work Item scope and return to this control plane when done; non-ThreeJS operations do not enter this process. Ordinary tasks do not require independent taskAuthorization, authorization records, or an F0 authorization validity gate; side-effect-free local A4 can be executed per task, while A4-A6 operations with side effects still retain per-object approval.

Shortest main closed loop

Popup-type transient display layers are handled according to theindependent work item rulesfor planning, implementation, and acceptance;hostSceneId is bound only to the runtime context and does not indicate ownership. A scene closes the loop only on its own gameplay, visuals, and persistent HUD; unfinished popups do not block scene V4, nor do they fall within the implementation scope of the lobby or other host scenes.

Users understand progress in daily work according to the six-stage project view of simplified-workflow.md : requirements and scope → global baseline → foundational engineering → per-scene production → global integration verification → release. A single-scene visual task advances within per-scene production according to scene definition → decomposition and layout confirmation → formal asset acceptance → formal restoration and runtime acceptance.

Read the current Work Item and record the user's original text, goals, scope, baseline, and acceptance boundaries; when changes occur within the task, update the plan accordingly.
Read the necessary reference according to the current stage, run run or check; when facts are missing, first ascertain them through code, configuration, existing artifacts, and authorized verification. Only when the remaining issues involve substantive user trade-offs that cannot be reasonably inferred should precise questions be raised; work that can proceed independently continues to be executed.
Before A3 implementation, freeze the implementation package; implementation units, execution status, visual evidence, and file ownership must be reviewable, and changes to paths, plans, or resource lists within the task may update that package.
After implementation, record a candidate change audit; first recommend the test level, rationale, coverage, and commands, then automatically execute targeted verification and submit the current candidate evidence; all tasks are judged for acceptance one by one according toactual completion status, and when the current requirements have been met, revising historical contracts is not a prerequisite for completion.
On failure, choose only according to evidence repair、revalidate or the necessary return; do not automatically roll back the shared workspace, expand scope, or repeat confirmed facts.
After a stage task meets the acceptance conditions, the executing agent automatically commits the changes for this task according to the following "Stage Wrap-up and Git Commit", then hands off to the next stage.

Stage Wrap-up and Git Commit

When temporary files for this task need to be cleaned up after stage acceptance, use threejs-game-artifact-cleanup to verify references and regeneration conditions before execution; when the user requests cleanup of historical records or intermediate artifacts, also route to that Skill. Retain valid evidence and the audit chain, and do not automatically delete due to record invalidation, task final state, or Git ignore; the cleanup scope and risk remain managed by this control plane.
After each stage's tasks are completed and pass the applicable verification, the executing agent automatically creates a local Git commit on the current branch without asking again; it does not automatically create branches, worktrees, or push to a remote.run、check and the state transition command itself do not perform Git commits.
At task start, record existing working tree and staging area changes; at wrap-up, verify the actual diff against task file ownership, and stage and commit only the additions, modifications, and deletions involved in this task. Indiscriminate use of git add . or git add -Ais prohibited; when the same file contains changes by others, isolate them by hunk, and if reliable separation is not possible, preserve the scene and report a blocker without including existing staged content.
Before committing, automatically check untracked files generated by this task and existing ignore rules, and add or update the project .gitignoreas needed, with the minimal scope ignoring dependency directories, caches, temporary files, local logs, regenerable build artifacts, and local secret configuration; include this task's .gitignore changes in the commit as well. Source code, necessary resources, lockfiles, deliverables, or evidence required for acceptance must not be ignored, nor may broad rules be used to conceal unfinished work.
.gitignore does not untrack already tracked files; only artifacts confirmed to belong to this task and that should not be committed are removed from the index while keeping local files, other historical files are not cleaned up in bulk, and ignored secret configuration is not force-added.
Before committing, check the selected diff and staged content, and use a concise Chinese commit message; after committing, verify the files included in the commit and the remaining working tree status, and report the commit hash, verification results, and uncommitted items. If there are no committable changes for this task, skip the empty commit. If verification fails, the commit fails, or file ownership is unclear, report the reason, do not claim wrap-up is complete, and do not skip Git hooks or automatically roll back.

Progressive reading

For routing or status queries only: read this file and the relevant passages in references/control-model.md .
When a state transition or gate decision is needed: then read references/state-gates.md。
When artifact fields are needed: read the corresponding references/*.schema.jsonby command, and do not preload the entire Schema.
When a visual task is needed: read references/visual-stage.schema.json and the corresponding domain contract; renderings, generative bitmaps, global baselines, and high-fidelity prerequisites are read only when applicable.
When A3 delegation, execution, or evidence is needed: read the corresponding implementation-package、delegation、execution-state、evidence Schema。

Non-bypassable constraints

INTAKE → BASELINE → PROPOSAL → REVIEW → IMPLEMENTING → VALIDATING → PASSED is an ordinary forward path;run continuously advances the safety control plane state that has already met the conditions, enters implementation or stops upon encountering missing evidence or a user decision, and never automatically selects RETURN。
The above stop refers only to the control command returning. The executing agent should continue to complete authorized implementation, evidence supplementation, fixes, and applicable verification, then invoke the control plane to advance; it pauses the corresponding work only when a necessary user decision, explicit approval, or an external blocker that cannot be eliminated on its own is missing, while work with no dependencies continues.
A0-A3 are based directly on the current user task; local A4 integration with no external side effects may also be executed per the task. Within a task, the plan, path, resource list, and verification scope may be adjusted, with the plan updated accordingly before continuing. A4-A6 operations involving external writes, payments, real devices, destructive or external deletions, or releases must create an exact pending item and obtain explicit approval for each object. The control plane does not perform these actions.
The actual artifacts of V0→V1→V2→V3→V4, manual selection of the global baseline, scenario V2 decomposition and layout confirmation, high-fidelity prerequisites, and V4 runtime acceptance must still be checked; handwritten status or a root PASS cannot replace actual files and applicable manual confirmation, and file references no longer require or compare SHA.
AUTO It only indicates that there are no additional product trade-offs, and does not replace global image selection, V2 breakdown, or independent layout manual confirmation. Each gate only requests the confirmation it still lacks; when the coverage facts and bound identity are unchanged, existing valid evidence is reused and no repeated inquiry is made.
Art direction and quality followGame art experience and quality contract. The structured brief for global image selection and the per-candidate manual quality results must pass through real file gates; if any selected candidate fails or is unverified, it cannot be frozen; the machine exit only checks facts and does not replace the manual results for viewing comfort, theme, and completeness, and without explicit authorization the agent does not automatically analyze screenshots or video frames.
Programmatic text is included as a hard constraint for implementation and review: English must be implemented at the same time en, Simplified Chinese zh-CN, Japanese ja, Russian ru, Spanish es, and display verification must be completed using each language's real glyph widths, baselines, font fallback, and container adaptation. While keeping the copy semantically accurate and understandable to players, it should remain short and game-like, prioritizing x3、+10, icon + value, and other familiar expressions, and not writing explanatory sentences that can be expressed directly by symbols. Each language independently declares a single-line or line-break strategy, allowing some languages to use a single line and others to use line breaks; truncation is prohibited. When it does not fit, the copy, letter spacing, font size, or container should be adjusted according to that language's strategy while maintaining a readable font size.
check read-only;run read-only validation, derive the route, and may continuously write safe state steps whose conditions have already been met, without running business code, tests, services, releases, or external actions.
Only when upstream facts, task scope, actual content, approval target, or implementation plan truly change should the affected parts be revalidated; missing or changed summaries do not invalidate old evidence. Adjustments to ordinary paths, plans, and resource lists within a task only update the plan and revalidate the affected parts. Overwriting others' modifications is prohibited.

Image task delivery

Effect image generation and interface implementation shareIn-game copyRule: internal planning notes and player-visible expression are kept separate, generation prompts clearly define the scope of visible text, and the formal interface binds the same expression and dynamic data. This applies to global candidates, scene key art, pop-ups, and paths without effect images; existing generation records, domain documents, and manual acceptance are reused, no new approval gates are added, and machine checks are not treated as copy display passing.

Visual tasks followImage-first confirmation method: the agent internally maintains analysis, technical records, and prompts, and directly delivers real images or previews for manual confirmation, without setting up routine pre-production confirmation gates for text proposals, breakdown records, layout decisions, or animation timelines. Rework within the confirmed target scope directly provides before-and-after comparisons; only decisive requirement ambiguity pauses the affected parts. Actual breakdown, layout, resources, parent frames, video confirmation, and operation authorization continue to use the original gates, and internal records cannot replace real candidates.

Lenient execution principle

All tasks and stages in the workflow cancel acceptance validation of SHA-1, SHA-256, file hashes, and candidate summaries: these fields are not required to be filled in, recalculated, or compared, and missing, malformed, or changed summaries do not block, return, or reopen tasks. Summary verification is left to the processing step after final manual acceptance; existing summaries are only optional tracking. Actual files, task ownership, applicable content constraints, command results, and manual confirmation must still be checked. Summaries for internal caching, plan display, and transactional concurrency protection are not acceptance gates.
Ordinary tasks do not establish independent authorization credentials. The user's current instruction simultaneously provides the execution basis for A0-A3; the Work Item only records the goal, scope, plan, and results, serving as collaboration context and tracking information.
All task and stage acceptance checks verify the current explicit requirements, actual results, and necessary constraints, judging the impact of differences one by one; non-mandatory implementation detail adjustments during the process only record the results and re-verify the affected evidence, without retroactively revising the contract or reopening completed work. Adjustments already explicitly raised by the user are directly incorporated into the current requirements; only when the scope, public interfaces, or hard constraints that subsequent dependencies truly rely on are changed are the corresponding contracts updated.
When non-critical metadata is missing, first remind and automatically fill it in; block only when identity, ownership, key artifacts, security boundaries, or the user's substantive trade-offs cannot be confirmed. Ordinary issues default to in-place repair, and when the candidate is unchanged, only revalidate。
Visual inspection by default checks usability and reasonable relationships, allowing small deviations in position, size, margins, and line wrapping; pixel-level tolerance and full-viewport/full-state matrices are enabled only when the user explicitly requests them or the project contract explicitly specifies them. Out-of-bounds, clipping, key occlusion, unreadability, and interaction failures must still be fixed.
Tests recommend T0-T3 based on change risk, displaying the rationale, coverage, and proposed execution commands, then automatically execute the applicable level; it does not wait for manual selection, nor does it automatically initiate real-device acceptance.

Agent entry

node <skill-dir>\scripts\workflow-control.mjs run --repo . --work-item <work-item> [--input <file> ...]
node <skill-dir>\scripts\workflow-control.mjs check --repo . --work-item <work-item> [--implementation-package <package>] [--evidence <manifest>] [--input <file> ...]
node <skill-dir>\scripts\workflow-control.mjs status --repo . --work-item <work-item> [--input <file> ...]

The three entries can repeatedly pass in --input <file> to bind explicit key inputs; by default the text preferentially displays the six-stage/four-step scenario view,--json still outputs a stable status/stage/changed/blocking/next/metadata top-level protocol, and in metadata.workflowView provides the display mapping,metadata.planFingerprint provides a deterministic plan fingerprint binding the baseline, authorization, status, implementation package, and key input file hashes. Repeated check must be read-only and produce consistent results.

Advanced diagnostics

route derives the route,preflight validates actions,advance migrates a state that has already satisfied a gate,transition performs explicit state transitions,diff-audit records candidate diffs,evidence-check validates evidence,delegate-check/parallel-check/unit-check manages A3 execution units,prepare-approval/handoff/approve serves only precise A4-A6 operations with side effects,lint performs repository-level static checks. Advanced commands do not change the above scope and hard-gate semantics.

Domain collaboration

$threejs-game-orchestrator is responsible for domain orchestration; production, architecture, gameplay, visual, asset, audio, numerical, QA, performance, and release Skills can only submit proposals, review conclusions, implementation packages, or evidence, and return to this control plane to complete state transitions.

Detailed states, gates, Schemas, visual contracts, and rework rules are respectively found in control-model.md、state-gates.md、schemas.md、visual-stage.schema.json and return-disposition.mjs。