hoatv2211/GameStudio-CodexKIT / skills/studio-project-scaffold
studio-project-scaffold
VerifiedUse when running gamestudio init, status, or uninit, or bootstrapping a new or adopted game repository with AGENTS.md, HANDOFF.md, .agents/CONTRACT.md, project governance, a subsystem registry, or a per-project adapter report, plan digest, named reviewer, backup root, generated agent overlay, apply, uninstall, and .codex/config.toml preservation.
scripts/studio_experience.py
View on GitHub# Generated by scripts/sync_skill_resources.py. Do not edit manually.
from __future__ import annotations
import re
from collections.abc import Iterable, Mapping
from dataclasses import dataclass
ROLE_IDS = ("developer", "qa", "producer", "liveops")
INTENT_IDS = ("diagnose", "verify", "plan-change", "ship", "handle-incident")
MODE_IDS = ("basic", "advanced")
def _copy_evidence_list(name: str, value: object) -> list[str]:
if not isinstance(value, list):
raise ValueError(f"{name} must be a list of non-empty strings")
snapshot = list(value)
if any(not isinstance(item, str) or not item.strip() for item in snapshot):
raise ValueError(f"{name} must be a list of non-empty strings")
return snapshot
def build_evidence_card(
*,
workflow: str,
verdict: str,
verified: list[str],
snapshot: list[str],
unverified: list[str],
blocked: list[str],
commands: list[dict[str, object]],
artifacts: list[str],
restore: str | None,
next_action: str,
) -> dict[str, object]:
"""Normalize caller-supplied evidence without collecting or inventing it."""
if verdict not in ("PASS", "FAIL", "BLOCKED"):
raise ValueError(f"unknown evidence verdict: {verdict}")
if not isinstance(workflow, str) or re.fullmatch(
r"[a-z0-9]+(?:-[a-z0-9]+)*", workflow
) is None:
raise ValueError("workflow must be a non-empty kebab-case string")
normalized_verified = _copy_evidence_list("verified", verified)
normalized_snapshot = _copy_evidence_list("snapshot", snapshot)
normalized_unverified = _copy_evidence_list("unverified", unverified)
normalized_blocked = _copy_evidence_list("blocked", blocked)
normalized_artifacts = _copy_evidence_list("artifacts", artifacts)
if not isinstance(commands, list):
raise ValueError("commands must be a list")
normalized_commands: list[dict[str, object]] = []
for command_evidence in commands:
if not isinstance(command_evidence, Mapping):
raise ValueError("command evidence must be a mapping")
if set(command_evidence) != {"command", "exit_code"}:
raise ValueError("command evidence requires command and exit_code")
command = command_evidence["command"]
exit_code = command_evidence["exit_code"]
if not isinstance(command, str) or not command.strip():
raise ValueError("command must be a non-empty string")
if isinstance(exit_code, bool) or not (
isinstance(exit_code, int) or exit_code is None
):
raise ValueError("exit_code must be an integer or None")
normalized_commands.append(
{"command": command, "exit_code": exit_code}
)
if restore is not None and not isinstance(restore, str):
raise ValueError("restore must be a string or None")
if not isinstance(next_action, str) or not next_action.strip():
raise ValueError("next_action must be a non-empty string")
if verdict == "PASS" and not normalized_verified:
raise ValueError("PASS requires verified evidence")
if verdict == "PASS" and normalized_blocked:
raise ValueError("PASS cannot include blockers")
if verdict == "PASS" and any(
command_evidence["exit_code"] != 0
for command_evidence in normalized_commands
):
raise ValueError("PASS requires every command to have exit_code 0")
if verdict == "BLOCKED" and not normalized_blocked:
raise ValueError("BLOCKED requires at least one blocker")
return {
"schema_version": 1,
"verdict": verdict,
"workflow": workflow,
"verified": normalized_verified,
"snapshot": normalized_snapshot,
"unverified": normalized_unverified,
"blocked": normalized_blocked,
"commands": normalized_commands,
"artifacts": normalized_artifacts,
"restore": restore,
"next_action": next_action,
}
@dataclass(frozen=True)
class _GoldenPath:
id: str
workflow: str
roles: frozenset[str]
intents: frozenset[str]
subsystems: frozenset[str]
risk_level: str
next_action: str
match_all_subsystems: bool = False
minimum_subsystem_matches: int | None = None
_GOLDEN_PATHS = (
_GoldenPath(
id="project-adoption-routing",
workflow="studio-project-intake",
roles=frozenset(ROLE_IDS),
intents=frozenset({"plan-change"}),
subsystems=frozenset(),
risk_level="read-only",
next_action=(
"Create the report-only project intake and repository routing packet."
),
),
_GoldenPath(
id="local-environment-recovery",
workflow="multi-service-local-environment-doctor",
roles=frozenset({"developer", "qa", "liveops"}),
intents=frozenset({"diagnose", "verify"}),
subsystems=frozenset({"server", "service", "services", "database"}),
risk_level="read-only",
next_action=(
"Inspect processes, ports, configuration, and prerequisites without "
"service control."
),
),
_GoldenPath(
id="unity-client-entry-recovery",
workflow="unity-client-offline-debugging",
roles=frozenset({"developer", "qa"}),
intents=frozenset({"diagnose"}),
subsystems=frozenset({"unity"}),
risk_level="read-only",
next_action=(
"Trace login, bootstrap, disconnected fallback, local data, and scene "
"entry."
),
),
_GoldenPath(
id="cpp-server-failure-recovery",
workflow="cpp-server-crash-triage",
roles=frozenset({"developer", "qa", "liveops"}),
intents=frozenset({"diagnose", "handle-incident"}),
subsystems=frozenset({"cpp", "server"}),
risk_level="read-only",
next_action=(
"Bind the crash signature to the exact build and rank the next diagnostics."
),
match_all_subsystems=True,
),
_GoldenPath(
id="cpp-server-failure-recovery",
workflow="mmorpg-packet-protocol-review",
roles=frozenset({"developer", "qa"}),
intents=frozenset({"diagnose", "verify"}),
subsystems=frozenset({"cpp", "server", "network"}),
risk_level="read-only",
next_action=(
"Review the packet manifest and server/client wire contract without mutation."
),
match_all_subsystems=True,
),
_GoldenPath(
id="unity-ui-localization",
workflow="unity-ui-rendering-debugging",
roles=frozenset({"developer", "qa"}),
intents=frozenset({"diagnose", "verify"}),
subsystems=frozenset({"unity", "ui"}),
risk_level="read-only",
next_action="Trace Unity UI hierarchy, sorting, anchors, and visible rendering.",
match_all_subsystems=True,
),
_GoldenPath(
id="unity-ui-localization",
workflow="localization-authority-audit",
roles=frozenset({"developer", "qa", "producer"}),
intents=frozenset({"diagnose", "verify", "plan-change"}),
subsystems=frozenset({"unity", "localization"}),
risk_level="read-only",
next_action=(
"Audit localization authority, generated copies, keys, encoding, and runtime consumers."
),
match_all_subsystems=True,
),
_GoldenPath(
id="unity-build-asset-integrity",
workflow="unity-batchmode-build-verification",
roles=frozenset({"developer", "qa", "producer"}),
intents=frozenset({"verify", "ship"}),
subsystems=frozenset({"unity", "build"}),
risk_level="read-only",
next_action="Verify the Unity batch build command, logs, artifact, and exit status.",
match_all_subsystems=True,
),
_GoldenPath(
id="unity-build-asset-integrity",
workflow="unity-asset-guid-meta-audit",
roles=frozenset({"developer", "qa"}),
intents=frozenset({"diagnose", "verify"}),
subsystems=frozenset({"unity", "assets"}),
risk_level="read-only",
next_action="Audit Unity GUID/meta consistency and stale asset references read-only.",
match_all_subsystems=True,
),
_GoldenPath(
id="lua-contract-server-authority",
workflow="lua-client-server-contract-audit",
roles=frozenset({"developer", "qa"}),
intents=frozenset({"diagnose", "verify"}),
subsystems=frozenset({"lua", "server", "network"}),
risk_level="read-only",
next_action="Compare normalized Lua client/server RPC contracts and protocol types.",
match_all_subsystems=True,
),
_GoldenPath(
id="lua-contract-server-authority",
workflow="network-authority-and-exploit-review",
roles=frozenset({"developer", "qa", "liveops"}),
intents=frozenset({"diagnose", "verify", "handle-incident"}),
subsystems=frozenset({"server", "network", "security"}),
risk_level="read-only",
next_action="Review server authority, replay, abuse, and rate-limit controls without exploitation.",
match_all_subsystems=False,
minimum_subsystem_matches=2,
),
_GoldenPath(
id="data-live-release-safety",
workflow="game-database-migration-safety",
roles=frozenset(ROLE_IDS),
intents=frozenset({"plan-change"}),
subsystems=frozenset({"database", "server"}),
risk_level="medium",
next_action="Plan a gated database migration with isolation, backup, restore, and approval checks.",
match_all_subsystems=True,
),
_GoldenPath(
id="data-live-release-safety",
workflow="save-data-schema-migration",
roles=frozenset({"developer", "qa", "producer"}),
intents=frozenset({"plan-change"}),
subsystems=frozenset({"save", "data", "server"}),
risk_level="medium",
next_action="Plan save-format versioning, fixture compatibility, conversion, and rollback checks.",
match_all_subsystems=True,
),
_GoldenPath(
id="data-live-release-safety",
workflow="release-candidate-preflight",
roles=frozenset({"qa", "producer", "liveops"}),
intents=frozenset({"ship"}),
subsystems=frozenset(),
risk_level="read-only",
next_action="Run a report-only release-candidate readiness and go/no-go preflight.",
),
_GoldenPath(
id="data-live-release-safety",
workflow="liveops-incident-response",
roles=frozenset({"producer", "liveops"}),
intents=frozenset({"handle-incident"}),
subsystems=frozenset(),
risk_level="high",
next_action="Coordinate incident containment, evidence, communications, and recovery checkpoints.",
),
)
def _as_mapping(value: object) -> Mapping[object, object]:
if isinstance(value, Mapping):
return value
return {}
def _defaults(
profile: Mapping[object, object],
) -> tuple[object, object, frozenset[str]]:
if "studio_experience" not in profile:
experience: Mapping[object, object] = {}
else:
configured_experience = profile["studio_experience"]
if not isinstance(configured_experience, Mapping):
raise ValueError("studio_experience must be a mapping")
experience = configured_experience
role = experience.get("default_role", "developer")
mode = experience.get("preferred_mode", "basic")
if "enabled_intents" not in experience:
return role, mode, frozenset(INTENT_IDS)
configured_intents = experience["enabled_intents"]
if not isinstance(configured_intents, list) or not configured_intents:
raise ValueError(
"studio experience enabled_intents must be a non-empty list"
)
enabled_intents: list[str] = []
for configured_intent in configured_intents:
if not isinstance(configured_intent, str):
raise ValueError("studio experience intent must be a string")
enabled_intents.append(configured_intent)
if len(set(enabled_intents)) != len(enabled_intents):
raise ValueError("studio experience enabled_intents must be unique")
for enabled_intent in enabled_intents:
if enabled_intent not in INTENT_IDS:
raise ValueError(f"unknown studio experience intent: {enabled_intent}")
return role, mode, frozenset(enabled_intents)
def _project_subsystems(profile: Mapping[object, object]) -> frozenset[str]:
repositories = profile.get("repositories")
if not isinstance(repositories, (list, tuple)):
return frozenset()
subsystems: set[str] = set()
for repository in repositories:
repository_mapping = _as_mapping(repository)
values = repository_mapping.get("subsystems")
if not isinstance(values, (list, tuple, set, frozenset)):
continue
for value in values:
if isinstance(value, str) and value.strip():
subsystems.add(value.strip().casefold())
return frozenset(subsystems)
def _installed_skills(available_skills: object) -> frozenset[str]:
if isinstance(available_skills, str):
return frozenset({available_skills})
if not isinstance(available_skills, Iterable):
return frozenset()
return frozenset(
skill for skill in available_skills if isinstance(skill, str)
)
def task_packet_semantic_errors(packet: object) -> list[str]:
"""Return deterministic cross-field task-packet coherence errors."""
if not isinstance(packet, Mapping):
return ["task packet must be an object"]
errors: list[str] = []
status = packet.get("status")
candidates = packet.get("candidates")
workflow_candidates = packet.get("workflow_candidates")
if not isinstance(candidates, list):
errors.append("candidates must be an array")
if not isinstance(workflow_candidates, list):
errors.append("workflow_candidates must be an array")
if status == "READY":
if isinstance(candidates, list) and candidates:
if packet.get("golden_path") != candidates[0]:
errors.append("READY golden_path must equal candidates[0]")
if isinstance(workflow_candidates, list) and workflow_candidates:
if packet.get("selected_workflow") != workflow_candidates[0]:
errors.append(
"READY selected_workflow must equal workflow_candidates[0]"
)
elif status == "AMBIGUOUS" and packet.get("golden_path") is not None:
if isinstance(candidates, list) and candidates:
if packet.get("golden_path") != candidates[0]:
errors.append("AMBIGUOUS golden_path must equal candidates[0]")
return errors
def _packet(
*,
status: str,
role: str,
intent: str,
mode: str,
golden_path: str | None,
selected_workflow: str | None,
candidates: list[str],
workflow_candidates: list[str],
questions: list[str],
prerequisites: list[str],
next_action: str,
risk_level: str = "read-only",
) -> dict[str, object]:
packet = {
"schema_version": 1,
"status": status,
"role": role,
"intent": intent,
"mode": mode,
"golden_path": golden_path,
"selected_workflow": selected_workflow,
"candidates": candidates,
"workflow_candidates": workflow_candidates,
"questions": questions,
"risk_level": risk_level,
"prerequisites": prerequisites,
"next_action": next_action,
}
semantic_errors = task_packet_semantic_errors(packet)
if semantic_errors:
raise ValueError("; ".join(semantic_errors))
return packet
def plan_experience(
profile: object,
*,
intent: str,
role: str | None = None,
mode: str | None = None,
requested_golden_path: str | None = None,
requested_workflow: str | None = None,
available_skills: Iterable[str] | None = None,
) -> dict[str, object]:
"""Select a role-aware Golden Path without executing or authorizing it."""
if not isinstance(profile, Mapping):
raise ValueError("project profile must be a mapping")
profile_mapping = profile
default_role, default_mode, enabled_intents = _defaults(profile_mapping)
selected_role = role if role is not None else default_role
if selected_role not in ROLE_IDS:
raise ValueError(f"unknown studio role: {selected_role}")
selected_mode = mode if mode is not None else default_mode
if selected_mode not in MODE_IDS:
raise ValueError(f"unknown studio mode: {selected_mode}")
if intent not in INTENT_IDS or intent not in enabled_intents:
raise ValueError(f"studio intent is not enabled: {intent}")
if requested_golden_path is not None and not isinstance(
requested_golden_path, str
):
raise ValueError("requested_golden_path must be a string")
if requested_workflow is not None:
if selected_mode != "advanced":
raise ValueError("workflow override requires advanced mode")
if not isinstance(requested_workflow, str):
raise ValueError("requested_workflow must be a string")
if not requested_workflow.strip():
raise ValueError("requested_workflow must be a non-empty string")
installed_skills = (
_installed_skills(available_skills)
if available_skills is not None
else None
)
project_subsystems = _project_subsystems(profile_mapping)
matches = sorted(
(
path
for path in _GOLDEN_PATHS
if selected_role in path.roles
and intent in path.intents
and (
not path.subsystems
or (
path.subsystems.issubset(project_subsystems)
if path.match_all_subsystems
else (
len(path.subsystems.intersection(project_subsystems))
>= (path.minimum_subsystem_matches or 1)
)
)
)
),
key=lambda path: (
-len(path.subsystems.intersection(project_subsystems)),
path.id,
path.workflow,
),
)
family_routes: dict[str, list[_GoldenPath]] = {}
family_scores: dict[str, int] = {}
for path in matches:
family_routes.setdefault(path.id, []).append(path)
family_scores[path.id] = max(
family_scores.get(path.id, 0),
len(path.subsystems.intersection(project_subsystems)),
)
family_order = sorted(
family_routes,
key=lambda family: (-family_scores[family], family),
)
prefilter_candidates = list(family_order)
if requested_golden_path is not None:
if requested_golden_path not in family_routes:
return _packet(
status="BLOCKED",
role=selected_role,
intent=intent,
mode=selected_mode,
golden_path=None,
selected_workflow=None,
candidates=prefilter_candidates,
workflow_candidates=[],
questions=[],
prerequisites=[
"Requested Golden Path is unavailable for the current role, "
f"intent, or project: {requested_golden_path}."
],
next_action="Select one of the reported candidate Golden Paths.",
)
matches = list(family_routes[requested_golden_path])
if requested_workflow is not None:
workflow_matches = [
path for path in matches if path.workflow == requested_workflow
]
if not workflow_matches:
candidate_families = sorted({path.id for path in matches})
available_workflows = sorted({path.workflow for path in matches})
return _packet(
status="BLOCKED",
role=selected_role,
intent=intent,
mode=selected_mode,
golden_path=(
requested_golden_path
if requested_golden_path in candidate_families
and len(candidate_families) == 1
else None
),
selected_workflow=None,
candidates=candidate_families,
workflow_candidates=available_workflows,
questions=[],
prerequisites=[
f"Requested workflow is unavailable for the current route: {requested_workflow}."
],
next_action="Select one of the reported workflow candidates.",
)
matches = workflow_matches
if installed_skills is not None and requested_workflow not in installed_skills:
selected_family = requested_golden_path or workflow_matches[0].id
return _packet(
status="BLOCKED",
role=selected_role,
intent=intent,
mode=selected_mode,
golden_path=selected_family,
selected_workflow=None,
candidates=[selected_family],
workflow_candidates=[],
questions=[],
prerequisites=[
f"Required workflow is not installed: {requested_workflow}."
],
next_action="Install the owning pack or full catalog before continuing.",
risk_level=workflow_matches[0].risk_level,
)
if not matches:
return _packet(
status="BLOCKED",
role=selected_role,
intent=intent,
mode=selected_mode,
golden_path=None,
selected_workflow=None,
candidates=[],
workflow_candidates=[],
questions=[],
prerequisites=["No Golden Path matches the detected project evidence."],
next_action=(
"Run studio-project-intake, or use Advanced presentation and select "
"a canonical skill directly outside gamestudio guide."
),
)
if requested_workflow is None and installed_skills is not None:
installed_matches = [
path for path in matches if path.workflow in installed_skills
]
if not installed_matches:
missing_workflows = sorted({path.workflow for path in matches})
family_ids = sorted({path.id for path in matches})
return _packet(
status="BLOCKED",
role=selected_role,
intent=intent,
mode=selected_mode,
golden_path=(family_ids[0] if len(family_ids) == 1 else None),
selected_workflow=None,
candidates=family_ids,
workflow_candidates=[],
questions=[],
prerequisites=[
"Required workflows are not installed: "
+ ", ".join(missing_workflows)
+ "."
],
next_action="Install the owning pack or full catalog before continuing.",
)
matches = installed_matches
if any(path.id == "lua-contract-server-authority" for path in matches):
matches = [
path for path in matches if path.id != "local-environment-recovery"
]
family_routes = {}
family_scores = {}
for path in matches:
family_routes.setdefault(path.id, []).append(path)
family_scores[path.id] = max(
family_scores.get(path.id, 0),
len(path.subsystems.intersection(project_subsystems)),
)
if not matches:
return _packet(
status="BLOCKED",
role=selected_role,
intent=intent,
mode=selected_mode,
golden_path=None,
selected_workflow=None,
candidates=[],
workflow_candidates=[],
questions=[],
prerequisites=["No Golden Path matches the detected project evidence."],
next_action=(
"Run studio-project-intake, or use Advanced presentation and select "
"a canonical skill directly outside gamestudio guide."
),
)
grouped_routes: dict[str, list[_GoldenPath]] = {}
for path in matches:
grouped_routes.setdefault(path.id, []).append(path)
candidate_ids = sorted(
grouped_routes,
key=lambda family: (-family_scores.get(family, 0), family),
)
if len(candidate_ids) > 1:
candidate_ids = candidate_ids[:2]
workflow_candidates = sorted(
{
path.workflow
for path in matches
if path.id in candidate_ids
}
)
if frozenset(candidate_ids) == frozenset(
{
"cpp-server-failure-recovery",
"local-environment-recovery",
}
):
question = (
"Is this a local environment problem or a build-bound server crash?"
)
else:
question = (
"Which Golden Path matches the current symptom: "
f"{candidate_ids[0]} or {candidate_ids[1]}?"
)
return _packet(
status="AMBIGUOUS",
role=selected_role,
intent=intent,
mode=selected_mode,
golden_path=None,
selected_workflow=None,
candidates=candidate_ids,
workflow_candidates=workflow_candidates,
questions=[question],
prerequisites=[],
next_action=(
"Answer the routing question before proceeding; this packet does not "
"authorize mutation."
),
)
selected_family = candidate_ids[0]
family_matches = grouped_routes[selected_family]
available_workflows = sorted({path.workflow for path in family_matches})
if len(available_workflows) > 1:
return _packet(
status="AMBIGUOUS",
role=selected_role,
intent=intent,
mode=selected_mode,
golden_path=selected_family,
selected_workflow=None,
candidates=[selected_family],
workflow_candidates=available_workflows,
questions=[
"Which canonical workflow matches the current symptom or requested outcome?"
],
prerequisites=[],
next_action=(
"Answer the workflow question before proceeding; this packet does not authorize mutation."
),
)
selected = family_matches[0]
if installed_skills is not None and selected.workflow not in installed_skills:
return _packet(
status="BLOCKED",
role=selected_role,
intent=intent,
mode=selected_mode,
golden_path=selected.id,
selected_workflow=None,
candidates=[selected.id],
workflow_candidates=[],
questions=[],
prerequisites=[f"Required workflow is not installed: {selected.workflow}."],
next_action="Install the owning pack or full catalog before continuing.",
risk_level=selected.risk_level,
)
return _packet(
status="READY",
role=selected_role,
intent=intent,
mode=selected_mode,
golden_path=selected.id,
selected_workflow=selected.workflow,
candidates=[selected.id],
workflow_candidates=[selected.workflow],
questions=[],
prerequisites=[],
next_action=selected.next_action,
risk_level=selected.risk_level,
)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 470k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |