GameDesignOS

Turn AI output into game design decisions you can verify.
Local-first · Evidence-linked · Human-gated

GameDesignOS is a local-first operating layer for AI-assisted game design. Bring an idea, gameplay sample, research trail, or workflow problem; get reviewable evidence, experiments, proposals, decisions, and project memory—without handing commitment-changing judgment to the agent.

简体中文 · Quick Start · Workflows · Cases · Roadmap

idea / gameplay / research / workflow
                  ↓
evidence → experiment → decision → learning
                  ↑
         Human Gate + rollback

Quick Start

git clone https://github.com/DY-2026/GameDesignOS.git
cd GameDesignOS
python -m pip install -e .
python -m gamedesignos demo
python -m gamedesignos ask "I want to validate a lighthouse tactics game"

demo makes no model calls and needs no key. It creates a fresh public-synthetic Lighthouse workspace in the system temporary directory, fills the Decision / Assumption / Evidence / reviewed Experiment chain, and stops before the decision accept Human Gate. ask recommends the smallest suitable skill without writing by default. For a persistent private project, create an explicit workspace:

python -m gamedesignos start "Lighthouse Tactics" --destination ../lighthouse-designos

Why This Exists

AI can draft faster than a team can decide. In game design, that often creates more fragments: chat logs, screenshots, one-off prompts, competitor notes, GDD drafts, experiment ideas, and half-remembered decisions.

GameDesignOS adds the missing operating layer. It turns agent output into reviewable project assets with provenance, contracts, gates, and rollback, so a designer can move from idea to evidence to experiment to decision without rebuilding context every session.

You still make the calls. The system supplies specialist workflows, shared handoffs, local state, and the discipline to stop at Human Gates.

What's Included

Development candidate: v1.3.0.dev0. Candidate wheels carry their own contracts/templates and router.yaml remains the only editable routing source. UL (Uncertainty Ladder) now has a machine-readable ul_state schema, UL-L0 through UL-L5, an optional workflow reference, and attribution/transfer regressions. All 7 skills still pass the Agent Skills reference validator; packaged behavior fixtures now cover 11 suites / 72 evals. The latest tagged stable source version is v1.2.0, and its GitHub Release is published as Latest.

Project-Ready Runtime

v1.2.0 keeps the local gamedesignos runtime Project-Ready and adds Intent Work Orders plus workflow-run.governance: AI work starts from the reality to change, every workflow can preserve intent / VOI / RJR / Human Gate / rollback / candidate-learning refs, and domain skills still own their specialist outputs. The CLI is deterministic and local-first: it creates v1 workspaces, manages Decisions, Assumptions, Evidence, Experiments, Gates, Workflows, and Learning, exports decision graphs, scans project health, and builds review-safe packs without calling a model.

Start a private workspace:

python -m pip install -e .
gamedesignos "I want to make a lighthouse tactics game"

The natural-language entry recommends the right skill without writing by default. Supply a destination or workspace to prepare the first Decision, Assumption, three-minute validation Experiment, VOI Gate, and workflow, or use the explicit start command. Existing skill folders remain independently installable; the runtime remains compatible with v0.8/v0.9 workspaces.

Read the v1.0 baseline plan, CLI guide, command reference, v1.2 release note, and product roadmap.

Decision-first research prompt:

Use $paranoia-ai-system-evolver to audit this research or AI workflow with a Decision Object, current default action, decision boundary, EVPI/EVSI, signal-to-action map, the smallest high-VOI probe, and a stop rule.

RJR-AI upgrade prompt:

Use $paranoia-ai-system-evolver to turn this AI workflow into an RJR-AI system: list what AI can search or draft, what workflow must constrain, what evals must test, what permissions block overreach, what knowledge should persist, and which residual judgments must stay with a human.

Intent Work Order prompt:

Use $paranoia-ai-system-evolver to upgrade this AI work order from an instruction sheet into an Intent Work Order: define the reality to change, project goal, desired outside-world state, verifier, first-glance acceptance, non-sacrifice boundaries, AI freedom, AI no-touch boundary, direction-change principles, delivery failure signals, and retrospective candidate learning.

What This Is

GameDesignOS is a local-first operating system for AI-assisted game design. It turns AI-agent sessions into durable design assets: decisions, assumptions, evidence, experiments, proposals, workflows, and learning records.

Its public base consists of a Skill Kernel, Contract Layer, Project Workspace, and executable Runtime Interface for concept validation, gameplay diagnosis, proposal writing, and workflow evolution.

The skills provide bounded expert behavior. Contracts make outputs interoperable. The workspace preserves project context. The runtime layer gives a host agent or local CLI deterministic commands for reading, routing, writing, validating, packing, and stopping at Human Gates.

It is not a scattered skill list or a prompt dump. It is closer to a compact operating system for serious game design work, with contracts that let skills hand work to each other instead of producing isolated prose:

media evidence -> evidence index -> issue cards -> ED handoff -> weekly experiments
one-line idea -> player-promise contract -> validation plan -> later media diagnosis
concept/evidence/production notes -> decision-ready proposal -> pitch or milestone gate
workflow change -> WOOP Task Card -> VOI/OODA probe -> eval -> Human Gate -> rollback
books and sources -> structured knowledge assets -> better references for future work

What Makes It Different

• Evidence-first: judgments point back to sources, screenshots, timestamps, sample evidence, or validation metrics.
• Contract-driven: concept briefs, evidence indexes, issue cards, ED handoffs, and validation plans can move across skills.
• Workspace-native: concepts, evidence, analysis, experiments, proposals, decisions, and retrospectives remain connected inside one project.
• Human-gated: agents can propose and structure work, but commitment-changing decisions are recorded by people.
• Residual-judgment authority: high-coupling, low-reversibility, under-evidenced choices stay human-owned while AI, workflow, evals, permissions, and memory align around the chosen direction.
• Decision-first information: before broad research, the system names the decision, current default action, decision boundary, signal-to-action map, information costs, and stop rule.
• Concept-to-validation: a promising idea becomes a seed, a player promise, a core loop, a scope gate, and a prototype test.
• Workflow-governed: useful behavior is written into SKILL.md, references/, templates/, evals, Human Gates, and rollback paths.
• Agent portable: Codex, Claude Code, OpenCode, or any Markdown-skill-capable agent can adapt the packages.
• Public/private safe: public examples stay synthetic, public, cleared, or marked needs_review; real projects stay in your own environment.

Try It in 5 Prompts

Use $game-experience-analyzer to diagnose this PV or gameplay recording into sample boundary, timestamped evidence, Hook/Loop/Link/Surprise diagnosis, issue cards, and validation recommendations.

Use $game-concept-architect to turn this one-line game idea into concept seed extraction, design nucleus options, player promise contract, core loop, scope gate, and prototype validation plan.

Use $game-design-proposal-writer to turn this concept brief, validation plan, evidence notes, and production constraints into a decision-ready commercial proposal, indie dossier, publisher pitch, or vertical-slice document.

Use $paranoia-ai-system-evolver to upgrade this workflow or AI work order into an Intent Work Order with a WOOP Task Card, VOI, OODA, eval checks, Human Gate, rollback, and retrospective candidate learning.

Use $game-experience-density-optimizer to turn this first-session retention, pacing, or experience density problem into an ED diagnosis, CLP/SF/EB/AR/MD-min levers, a weekly A/B plan, instrumentation, dashboard fields, decision rules, and rollback gates.

For the full onboarding path, see Try It in 10 Minutes.

60-Second Demo

Start with one screenshot, gameplay recording, trailer/PV, or video link. Ask the skill for an evidence-linked report:

Use $game-experience-analyzer to analyze this gameplay recording into timestamped evidence, feature exposure/unlock/first-use ledger, Hook/Loop/Link/Surprise diagnosis, and actionable fixes.

For concrete proof paths, continue to the cases below. The demo above shows the fast interaction pattern; the cases show reviewable outputs and their evidence boundaries.

Featured Cases

If you are browsing on GitHub, start with these two cases. The first shows a single gameplay recording turning into a Game Experience Analyzer report; the second shows how public video evidence flows into an Experience Density experiment package.

Easy Start

For ongoing work, start a project workspace so context persists. For a one-off task, you can still call a skill directly.

1. Start a project workspace

python -m pip install -e .
gamedesignos "I want to make a lighthouse tactics game"

Keep private material outside this public repository. The natural-language entry remains route-only unless you supply a destination or workspace; use start for an explicit long-lived project setup.

2. Pick the right skill

3. Copy a minimal prompt

Call a skill directly in an agent environment that supports skill loading:

Use $game-experience-analyzer to analyze this gameplay recording into timestamped evidence, design lenses, heat potential, foresight windows, Go/No-Go, and validation recommendations.

Use $game-experience-analyzer to dissect this game into player verbs, action-goal alignment, uncertainty sources, system dynamics, content flow, audience desire, transfer boundaries, and validation recommendations.

Use $paranoia-ai-system-evolver to upgrade this prompt/workflow/schema/work order into an Intent Work Order with WOOP, VOI, OODA, evals, Human Gate, rollback, and retrospective candidate learning.

Use $game-design-book-translator to translate and polish this game design chapter into professional Chinese, including terminology and figure captions.

Use $game-design-source-curator to review these game design sources and turn accepted items into a maintainable local knowledge base.

Use $game-concept-architect to turn this one-line game idea into a concept seed, player verbs, action-goal alignment, player promise, core loop, scope gate, production feasibility check, and prototype validation plan.

Use $game-design-proposal-writer to assemble this research, concept brief, evidence index, validation plan, and team constraints into a publisher pitch outline with proof of play, scope gate, budget assumptions, risks, and decision request.

Use $game-experience-density-optimizer to turn this first-session experience density problem into CLP/SF/EB/AR/MD-min diagnosis, rollbackable weekly variants, telemetry events, dashboard fields, and pre-registered decision rules.

4. Install a skill in your own agent environment

If your tool supports local skills, copy the target folder into that tool's skill directory:

game-experience-analyzer/
paranoia-ai-system-evolver/
game-design-book-translator/
game-design-source-curator/
game-concept-architect/
game-experience-density-optimizer/
game-design-proposal-writer/

After installation, check that the SKILL.md frontmatter name matches the folder name, and that relative links inside references/, templates/, and examples/ still resolve.

Showcase

Seven bounded entry points cover the main GameDesignOS workflow: concept architecture, evidence and diagnosis, proposal assembly, experience-density iteration, workflow governance, design-text translation, and source curation.

Architect game concepts Turn a one-line idea into a seed, player verbs, action-goal alignment, player promise, core loop, scope gate, and validation plan.	Analyze game experience Convert screenshots, recordings, trailers, and video links into evidence-first diagnosis, game dissection, and mechanic-transfer judgment.	Assemble proposals Turn research, concept contracts, evidence notes, validation plans, and production constraints into review-ready proposals and pitches.	Optimize experience density Turn retention, pacing, feedback, embodiment, atmosphere, and cognitive-load issues into weekly ED experiments.

Evolve workflows Upgrade prompts, schemas, evals, memory, and tool routing through WOOP, VOI, OODA, gates, and rollback.	Translate design knowledge Transform serious game design books and chapters into professional Chinese design writing.	Curate sources Turn scattered articles, videos, creators, columns, and websites into a durable game design knowledge base.

For the compact proof-path list, see the showcase index.

System Architecture

GameDesignOS is organized as four product layers plus a cross-cutting governance plane. The current v1.3 candidate adds optional UL between VOI selection and OODA execution without migrating the v1 workspace schema:

• Skill Kernel
  • game-concept-architect/: one-line idea -> verifiable design blueprint.
  • game-experience-analyzer/: media/sample -> evidence-linked diagnosis.
  • game-experience-density-optimizer/: bounded experience problem -> weekly experiment.
  • game-design-proposal-writer/: concept/evidence/constraints -> decision-ready proposal.
  • paranoia-ai-system-evolver/: workflow/schema/eval change -> controlled evolution.
  • game-design-book-translator/: design texts -> professional Chinese design writing.
  • game-design-source-curator/: scattered sources -> durable knowledge base.
• Contract Layer
  • contracts/: routing, skill handoffs, ul-state.schema.json, project manifests, asset indexes, and decision logs.
• Project Workspace
  • runtime/workspace-template-v1/: project identity, lifecycle directories, asset registry, learning records, exports, and Human Gates.
• Runtime Interface
  • gamedesignos/, runtime/, and adapters/: local CLI commands, workspace lifecycle, host integration, and command contracts.
• Governance
  • evidence boundaries, public/private separation, VOI, optional UL, RJR-AI, evals, Human Gates, and rollback apply across every layer.

Private overlays, real project data, client examples, credentials, and local studio rules should live outside this public repository. Users may still run any skill directly without adopting a workspace.

Current Skills

Use Cases

• Competitor experience review: turn a gameplay recording into a timeline, feature ledger, loop diagnosis, issue priority, and concrete fixes.
• Game dissection and mechanic transfer: break a sample into player verbs, goal layers, uncertainty, system dynamics, content flow, audience desire, playable theme, and transfer boundaries.
• Trailer heat prediction: evaluate first seconds, one-line value proposition, proof of play, channel fit, conversion path, and validation plan.
• Foresight opportunity: judge whether a genre, theme, or mechanic still has a window; casual/light defaults to 1-3 months, micro/midcore-heavy defaults to 3-6 months.
• Source curation: turn articles, videos, creators, columns, and websites into searchable, citable, experiment-ready design knowledge.
• Professional translation: translate game design books or essays while preserving terminology, argument structure, and figure context.
• Workflow evolution: promote useful agent behavior into candidate rules with evals, Human Gate, and rollback.
• Cross-skill handoff: move from concept promise to media diagnosis to ED experiment through shared contracts instead of rewriting context by hand.
• Concept feasibility: turn a one-line idea into concept seed extraction, player verbs, action-goal alignment, player promises, core loop design, scope gate, production feasibility, and prototype validation.
• Proposal assembly: turn validated concepts, source notes, evidence, risks, and production constraints into reviewable commercial proposals, indie dossiers, pitch outlines, or vertical-slice documents.
• Experience density experiments: turn first-session, pacing, feedback, embodiment, atmosphere, or cognitive-load issues into weekly ED experiments with metrics and rollback gates.

Repository Layout

Read the repository as a GameDesignOS public base rather than a normal asset folder.

Most skills follow this structure:

SKILL.md      -> agent entrypoint, triggers, workflow, boundaries
references/  -> methods, scoring rules, routers, gates, validation playbooks
templates/   -> reusable forms and output structures
examples/    -> reviewable example outputs
agents/      -> metadata for agent environments that support it
evals/       -> regression prompts and expected behavior

Install And Use

GameDesignOS supports two compatible modes.

Project Workspace Mode

Install the local runtime and start with one sentence. The request remains route-only unless a destination or workspace is supplied; use start to explicitly prepare the first validation path.

python -m pip install -e .
gamedesignos "I want to make a lighthouse tactics game"

Direct Skill Mode

1. Copy or sync a skill folder into your agent skill directory.
2. Confirm the SKILL.md frontmatter name matches the folder name.
3. Trigger the skill by $skill-name or natural language.
4. Validate JSON/YAML, reference paths, and examples according to the skill README or SKILL.md.

The workspace layer does not prevent direct skill use.

Validation

Run these commands from the repository root:

python scripts/validate_repo.py
python scripts/validate_skill.py game-experience-analyzer
python scripts/validate_skill.py game-concept-architect
python scripts/validate_skill.py game-experience-density-optimizer
python scripts/validate_skill.py game-design-proposal-writer
python -m unittest discover -s scripts/tests
gamedesignos --version
gamedesignos doctor

Roadmap

• v0.8.0 — Runtime Foundation: workspace template, workspace contracts, product architecture, workflow routes, and validation.
• v0.9.0 — Local Runtime Prototype: initialize, inspect, route, create, validate, and pack local workspaces.
• v1.0.0 — Project-Ready GameDesignOS: tagged stable baseline with the Decision/Assumption/Evidence/Experiment/Gate/Workflow/Learning chain, decision graph, health scan, Human Gate, and v1 workspace.
• v1.1.0 — RJR-AI Authority Layer: residual judgment boundaries, GitHub positioning, version sync, and workflow-evolution coverage for AI/workflow/eval/permission/memory systems.
• v1.2.0 — Intent Work Order & Workflow Governance: AI work orders, workflow-run governance refs, Paranoia checkpoints, release tag cleanup, and runtime/package version sync.
• v1.3.0.dev0 candidate — Portable Runtime & UL: self-contained wheel resources, one router source, ul_state schema, UL-L0 through UL-L5, optional workflow references, and transfer gates; not tagged or published.
• v1.x — Proof and adoption: more public cases, adapter hardening, runtime dashboards, and validated real-project playbooks.

See the capability-gated product roadmap.

Support the Project

If GameDesignOS is useful to you, star the repository or open an issue with a concrete workflow, proof-case, or adapter request. Stars and actionable feedback help prioritize the next public examples and portability work.

License

Skill documents and tooling in this repository are released under the MIT License.

The Paranoia name, logos, visual identity, and project branding are not licensed as trademarks. Examples may have their own source_status, case_type, or source metadata; check each example's frontmatter before reuse.

Package Conventions

Each skill is an independently installable package. Keep SKILL.md as the runtime entrypoint, put durable methods in references/, reusable forms in templates/, examples in examples/, and regression checks in evals/.

Contributing

Public examples, evals, assets, showcases, and release notes must use synthetic, public, or explicitly cleared material. See CONTRIBUTING.md before submitting repository-facing content.

Design Principles

Evidence before opinion.
Feasibility before scope.
Workflow before one-off prompts.
VOI before research.
Eval before promotion.
Rollback before confidence.

Future Skills

Depending on feedback and maturity, future additions may include AI + indie game production packages such as:

• indie-game-production-master: full-cycle indie production from idea validation, GDD/Gates, prototyping, playtesting, AI asset pipelines, Steam/release strategy, and postmortem writeback.
• godot-ai-game-production: Godot + AI production covering project scaffolding, design truth, data contracts, asset pipelines, headless/keyshot validation, Demo/Release Gates, and engineering retrospectives.