GameDesignOS: A Local-First Operating System for AI-Assisted Game Design
Turns AI sessions into verifiable evidence, experiments, and reviewable decisions with Human Gates, rollback, and durable project memory.
Strong evidence: CI uses contents:read only; reference-host tests verify preview-first flow, explicit --execute approval, API keys never persisted, changed tasks cannot reuse reviewed previews, and transport failures yield outcome_unknown with no blind retry. SECURITY.md requires Human Gates for publish/delete/permission changes. Deducted: external-effects enforcement in real host environments is unverifiable statically; publisher is pseudonymous ('Paranoia'), attribution limited.
Minimal pinned-floor dependencies (PyYAML, schema), CI across three Python versions and two OSes, 80% coverage baseline. Deducted: dependency availability and failure-message quality are not executable-verified here; error messaging is only indirectly evidenced by tests.
README clearly defines audience, seven bounded skills, four host adapters, and v0.8/v0.9 workspace compatibility. Deducted: trigger precision depends on host skill-loading mechanics not fully shown; Python>=3.11 requirement is documented but compatibility matrix is not execution-verified.
Clear four-layer architecture, complete install notes (editable install, demo, ask, start), dual MIT declaration (LICENSE file plus pyproject), explicit public/private data separation, rich cases and demos. Deducted: pseudonymous individual maintainer with security fixes only for latest main/release; parallel v1.2.0/v1.3.0.dev0 versioning requires reader effort to reconcile.
Key-free demo, read-only routing default, reusable workspace template and contracts; marginal value lies in converting scattered AI output into reviewable assets. Deducted: output usability and cost/benefit require actual runs; static evidence shows design intent and test coverage, not realized utility.
Tests, CI configuration, and README claims cross-corroborate (72 evals, validator, CLI smoke). Deducted: behavior-eval fixture contents are not shown in provided files, so some claims rest on CI setup existence rather than inspectable results; no execution performed.
- Publisher is an unverified pseudonym ('Paranoia'); perform supply-side due diligence before enterprise adoption.
- This is a static review with no execution; the claimed 11-suite/72-eval behavior fixtures and 80% coverage should be re-run independently.
- The reference host sends data to an external OpenAI-compatible endpoint; review payload contents and endpoint configuration in a controlled environment.
- Security fixes cover only the latest main and latest stable release; workspace-schema compatibility does not imply continued maintenance of old runtimes.
- Current revision is a v1.3.0.dev0 development candidate; contracts and templates may change—pin the v1.2.0 tag for production use.
What does this agent do, and when should you use it?
GameDesignOS is a local-first operating layer for AI-assisted game design that turns scattered agent output into reviewable project assets: decisions, assumptions, evidence, experiments, proposals, workflows, and learning records. The repository ships four layers: 7 independently installable specialist skills (such as $game-experience-analyzer and $game-concept-architect), 19 contract schemas under contracts/, a v1 workspace template, and a deterministic local CLI named gamedesignos. The CLI never calls a model; it handles workspace creation, routing, validation, health scans, decision-graph export, and review-safe packing, while all commitment-changing decisions must pass a Human Gate owned by a person. Runtime state lives in a separate .gamedesignos/ directory, so real project data can stay in your private environment. The latest stable release is v1.2.0, with a v1.3.0.dev0 development candidate adding a machine-readable ul_state schema and UL-L0 through UL-L5.
After installing with python -m pip install -e ., run python -m gamedesignos demo to walk a full Decision/Assumption/Evidence/Experiment chain offline; use python -m gamedesignos ask "..." or gamedesignos "<one-line idea>" for route-only skill recommendation, or the start command to create a persistent private workspace. The skill layer reads screenshots, gameplay recordings, trailers, one-line ideas, or workflow descriptions and produces timestamped experience reports, concept blueprints with player-promise contracts and scope gates, weekly ED (experience-density) experiment plans, decision-ready proposals, Intent Work Orders with WOOP/VOI/OODA/evals/rollback, professional Chinese translations, and curated knowledge-base entries. The contract layer lets skills hand work to each other via evidence indexes, issue cards, ED handoffs, and validation plans. Validation is provided by scripts/validate_repo.py, per-skill validators, unittest suites, gamedesignos doctor, and rollback gates.
- An indie developer with a one-line game idea uses $game-concept-architect to produce a concept seed, player verbs, player promise, core loop, scope gate, and prototype validation plan
- A designer with a competitor recording or trailer uses $game-experience-analyzer for timestamped evidence, feature ledgers, early-loop diagnosis, and prioritized fixes
- A live-ops owner facing retention or pacing issues uses $game-experience-density-optimizer to plan weekly A/B variants, telemetry fields, dashboards, and rollback gates
- A team assembling a publisher pitch or vertical-slice document uses $game-design-proposal-writer to merge evidence, validation notes, and production constraints
- An engineer uses $paranoia-ai-system-evolver to turn prompts, schemas, and workflows into governed Intent Work Orders with evals, Human Gates, and rollback
- A translator or researcher uses $game-design-book-translator and $game-design-source-curator to build professional Chinese translations and a durable local design knowledge base
What are this agent's strengths and limitations?
- Deterministic local CLI makes no model calls; demo runs fully offline and private projects stay on your machine
- Contract-driven skill handoffs (19 schemas) preserve context across sessions instead of rebuilding it each time
- Human Gate + rollback + RJR-AI residual-judgment boundaries keep high-coupling, low-reversibility decisions human-owned
- All 7 skills pass the Agent Skills reference validator; packaged behavior fixtures cover 11 suites / 72 evals
- Much of the value depends on adopting the workspace and contract layers; one-off skill calls gain less
- Many report outputs are Chinese-first, which may require adaptation for English-only teams
- The v1.3.0.dev0 candidate is untagged and unpublished, so stable users lack UL and the newest portability features
- Only 2 public proof cases exist, marked synthetic or needs_review, limiting public evidence of real-project results
- Skills rely on SKILL.md-based host loading; non-standard agent environments require manual copying and link checks
How do you install or deploy this agent?
Requires Python and a local shell:
git clone https://github.com/DY-2026/GameDesignOS.git
cd GameDesignOSpython -m pip install -e .
Verify:
python -m gamedesignos demo # no model calls, no key needed
python -m gamedesignos doctor # health checkAlternatively, copy an individual skill folder (e.g., game-experience-analyzer/) into an agent environment that supports local skills, and confirm the SKILL.md frontmatter name matches the folder name and relative links still resolve.
How do you use this agent?
Three modes:
1) Persistent project: gamedesignos "I want to make a lighthouse tactics game" (route-only by default), or python -m gamedesignos start "Lighthouse Tactics" --destination ../lighthouse-designos for an explicit long-lived workspace.
2) Direct skill call: in a skill-capable agent, enter e.g. "Use $game-experience-analyzer to analyze this gameplay recording into timestamped evidence...".
3) Quick ask: python -m gamedesignos ask "I want to validate a lighthouse tactics game" recommends the smallest suitable skill without writing. Validation: python scripts/validate_repo.py, python scripts/validate_skill.py <skill>, python -m unittest discover -s scripts/tests, gamedesignos --version.