SpecOps Unity Reference Implementation

specops-unity-reference-implementation is a public reference repository demonstrating one concrete combination of SpecOps AI v2 and a selected Unity Clean Architecture.

The latest published Golden Baseline is v2.0.2. This main source tree is mutable current development and remains distinct from the immutable published release, even where their histories previously shared the same commit.

Current Status

The latest published Golden Baseline is v2.0.2.

The v2.0.2 release is published and immutable. Its annotated tag, GitHub Release, and release-bound evidence are the authoritative publication and identity records for that version.

The main branch is mutable current development. It may move beyond the latest immutable release, so contributors must not infer that future main state is the published Golden Baseline.

For a new stable Unity project, use the published v2.0.2 release source and follow INSTALL.md, rather than using current development from main.

See the changelog for public change history and the GitHub Releases for published release state.

What This Repository Is

• A public reference implementation of SpecOps AI v2 applied to a Unity repository.
• A concrete example of a selected layered Unity Clean Architecture.
• The development repository for a reference implementation whose latest published Golden Baseline can be used to bootstrap disciplined Unity projects.
• A place to examine how specifications, authority, permissions, implementation boundaries, and validation evidence fit together.

What This Repository Is Not

• The generic SpecOps Core repository.
• Project Reclaimer.
• A finished game.
• A claim that this architecture is mandatory for every Unity project.
• A claim that mutable current development on main necessarily equals the latest immutable published release.

Current Authority

The repository has four current-authority domains:

Domain	Current authority
SpecOps framework semantics	Assets/Project/Docs/SpecOps/SPECOPS_V2.md
Unity structure and dependency boundaries	Assets/Project/Docs/Architecture/ARCHITECTURE.md
Repository-wide engineering constraints	Assets/Project/Docs/Governance/GLOBAL_CONSTRAINTS.md
Approved feature intent	Assets/Project/Docs/Specifications/<feature>/SPEC.md, CONSTRAINTS.md, and ACCEPTANCE.md

Start with these documents before relying on workflow guides, templates, Skills, .specops/*, ADRs, plans, or validation records. Those artifacts are derived or subordinate and cannot silently override current authority.

For an operational entry path, read the public onboarding guide and derived workflow.

Selected Unity Clean Architecture

The reference architecture has seven runtime layers:

• Domain — enterprise rules and core models; pure C# with no Unity engine references.
• Application — use cases, orchestration, and ports; depends on Domain and has no Unity engine references.
• AI — AI strategies and policies built on Application and Domain.
• Infrastructure — persistence, networking, files, platform services, and other adapters.
• Presentation — Unity-facing views, input translation, and scene hooks.
• Composition — VContainer lifetime scopes and registrations; wiring rather than gameplay logic.
• Utility — shared cross-cutting helpers and logging abstractions.

Domain and Application assemblies retain noEngineReferences = true. The architecture document defines allowed dependency directions; it does not require every allowed dependency to exist physically.

The repository uses InfiniteMonkey.* assembly names. VContainer is present for composition and Moq is present for test isolation where appropriate. Neither dependency is mandatory ceremony for every implementation or test.

Latest Published Golden Baseline

The latest published Golden Baseline is v2.0.2.

That release is immutable. Detailed release identities, qualification evidence, validation results, evidence hashes, and publication records belong to the annotated tag, GitHub Release, and release-bound evidence rather than being duplicated here as mutable current-state claims.

For v2.0.2:

• Unity editor: 6000.5.8f1 (revision 5cb7df797b7d).
• Default IDE target: JetBrains Rider.
• Repository VCS and hosting: Git and GitHub.

For stable project bootstrap, use the published release source rather than main. The root INSTALL.md describes the supported installation path.

Rider is the verified/default Golden Baseline IDE direction for this repository deployment. It is not a SpecOps framework requirement, and user-global Rider or tool settings must never be silently changed. Codex, Junie, and deterministic tools may be deployment executors; they do not define SpecOps logical roles. See deployment guidance.

Repository Layout

• Assets/Project/Code/Runtime — seven layered runtime assemblies.
• Assets/Project/Code/Tests — EditMode and PlayMode test assemblies.
• Assets/Project/Editor — editor-only tooling.
• Assets/Project/Docs — framework, architecture, governance, workflow, and feature documentation.
• Assets/Project/Docs/Specifications — feature authority instances and canonical templates.
• Assets/ScriptTemplates — retained Unity script templates.

See Assets/Project/README.md for the detailed Unity asset and code layout.

Getting Started

For a step-by-step guide to creating a new Unity project from the published Golden Baseline, see INSTALL.md.

1. Read the onboarding guide.
2. Read the applicable current authority listed above.
3. Confirm the editor version in ProjectSettings/ProjectVersion.txt and review current package declarations in Packages/manifest.json.
4. Inspect the project structure and InfiniteMonkey.* assembly definitions under Assets/Project/Code.
5. Open Unity or allow package resolution only when appropriate for your task and environment; report those actions and their results as evidence.
6. Run only the validation relevant to the change. Distinguish static inspection, compilation, EditMode tests, PlayMode tests, and manual Unity checks.

Production Bootstrap Workflow

The public construction path is: canonical LF source → production Bootstrap → fresh Unity child → Unity 6000.5.8f1 validation. Source bytes are bound by the committed projection manifest, and repository policy uses canonical LF bytes. Obtain the current approved Source Identity from the committed projection manifest and governed Bootstrap metadata rather than copying a digest into authored documentation.

Invoke tools/specops/bootstrap/Invoke-SpecOpsBootstrap.ps1 from a conforming physical source with these six required inputs:

• DestinationPath
• ProjectId
• ProductName
• CompanyName
• ApplicationIdentifier
• CodeNamespaceRoot

The destination must satisfy the freshness and safety requirements in the Bootstrap contract. Bootstrap provenance records construction lineage only: the generated child inherits no release evidence or approval. Unity version and support requirements come from committed authority and project bindings, including ProjectSettings/ProjectVersion.txt.

Feature Specifications

Feature authority is an approved triplet under Assets/Project/Docs/Specifications/<feature>/:

• SPEC.md — intent, goals, non-goals, and requirements.
• CONSTRAINTS.md — feature-specific constraints.
• ACCEPTANCE.md — stable, testable acceptance criteria.

SPECOPS_STATE.json is derived traceability state and never authority. Templates are unapproved scaffolding; copying them does not approve a feature.

Read the Specifications index before creating or changing a feature specification.

Validation Philosophy

Evidence comes before a verdict. A validation report must identify what was executed, what was not executed, the actual results, limitations, and unresolved unknowns.

• Prefer deterministic checks when they directly establish the required evidence.
• Use EditMode tests for pure logic and PlayMode tests when Unity lifecycle, frames, scenes, or runtime behavior is material.
• Do not infer compilation or test success from scaffolding, documentation, package declarations, or an earlier run.
• Never report PASS for a check that did not run.

Git and GitHub

Git and GitHub are repository-instance choices, not universal SpecOps requirements. Keep changes bounded, inspect the complete diff, preserve unrelated work, and follow the repository's issue and pull-request guidance.

Commits, pushes, merges, tags, releases, history mutation, and external publication remain human-controlled consequential operations. Completing one migration slice does not authorize the next slice or publication.

Contributing

Public contributions are welcome when they preserve the repository's reference purpose and authority boundaries. Read CONTRIBUTING.md before opening an issue or pull request.

In particular, discuss architecture, dependency, Packages/*, ProjectSettings/*, assembly-topology, compatibility, or broad migration changes before implementation. Prefer small, evidence-backed changes over unrelated cleanup or broad rewrites.

License and Attribution

This repository is published under the Apache License 2.0.

Copyright 2026 Infinite Monkey Theorem AB. Preserve the repository attribution and publication notices in NOTICE when redistributing the work.