studio-project-scaffold

Studio Project Scaffold

Overview

Create the minimum project-local governance, project profile, routing references, and agent-role overlay needed for safe multi-session work while preserving existing instructions, configuration, skills, and agents.

Newly generated profiles include optional studio_experience defaults for role, mode, and enabled intents. These defaults affect routing presentation only. Use gamestudio guide for a report-only Golden Path packet; gamestudio init --apply remains a separate reviewed mutation.

When to use

Use for a new game repository, an inherited legacy project without agent governance, or a project that needs standardized ownership, evidence labels, and handoff state.

When NOT to use

Do not overwrite a mature project-local .agents/ system, existing AGENTS.md, HANDOFF.md, or skills. Generate a report and merge plan instead.

Required inputs and context discovery

Collect workspace root, nested Git roots, Git state, existing governance files, Unity markers, server projects, Lua/data trees, database inputs, generated, cache, vendor, and excluded paths, project-local skill IDs, agent files, and .codex/config.toml state.

Safety and risk level

Scaffolding and the per-project adapter are medium-risk because they write governance and agent files. Run report-only first, preserve every existing file by default, and never mutate external projects during kit tests.

Workflow

1. Scan structure read-only and detect Unity, server, Lua, database, tooling, and generated subsystems. Completion criterion: detected subsystems and unknown areas are reported.
2. Inventory existing AGENTS.md, HANDOFF.md, .agents/, local skills, and ignore rules. Completion criterion: every existing governance artifact is marked preserve, merge, or BLOCKED.
3. Render the minimum scaffold with evidence, ownership, repeated-work tooling, mutation, generated-file, no-touch rules, project profile, workspace map, validation matrix, and adapter references. Completion criterion: scaffold-report.json lists exact proposed and preserved scaffold files without writes.
4. Run the per-project adapter report-only first. Review plan_digest, proposed planned paths, collisions, activated_roles, scope_review, preserved paths, and the action/hash details under mutation_report.operations. Broad resolved capability intersections are advisory; only out-of-scope or duplicate exact active write assignments block orchestration. Completion criterion: the reviewed adapter report identifies every proposed write and collision without mutation.
5. Apply only that reviewed adapter plan with a named reviewer, a disjoint project-local backup root, and the approved plan digest. Generate and review a new report when the digest is stale. Completion criterion: apply uses all three gates and returns its manifest and restore command.
6. Materialize roles from packaged generic agent templates plus profile and inferred specialists under .codex/agents/, preserving an explicit project reasoning_effort over the template default. The generated .codex/agents.generated.toml file remains inert until manual merge, and the adapter leaves .codex/config.toml untouched. Completion criterion: unmanaged agents and active configuration remain preserved, and effective scopes are reviewed only after role resolution.
7. Record per-file ownership hashes under .agents/registry.json, then run project-local validation and inspect the generated handoff snapshot. Completion criterion: scaffold output is parseable and unresolved runtime facts remain Unverified or BLOCKED.
8. Run uninstall report-only first and review its plan_digest, proposed, preserved_drift, and remaining_owned paths. Apply only with a named reviewer, a disjoint backup root, and that matching digest. Use hash-safe uninstall: remove only files matching recorded ownership hashes. Preserve drift and return PARTIAL with preserved_drift and remaining_owned for manual recovery when safe cleanup cannot finish. Completion criterion: uninstall never deletes unmanaged or drifted project content and cannot bypass the approval gates.