AIRoot

Public reusable AI operating layer for repo-attached engineering workflows.

AIRoot is the part you can publish, reuse, version, and mount into other repositories without carrying project-specific memory, host-private routing, or mutable operational state with it.

What This Repo Is

Use AIRoot when you want a reusable layer for:

• AI protocol modules
• setup and integration guidance
• visual architecture maps
• operational handbooks
• templates and bootstrap scripts
• design and roadmap documents

The public execution core in this repo is xuunity, a Unity-focused protocol family for engineering, review, SDK work, product-facing implementation questions, and protocol maintenance.

What This Repo Is Not

AIRoot is not the runtime source of truth for a real production host repo.

In an attached host, the source of truth typically lives in:

• a repo router such as Agents.md
• host-local private modules or overlays when needed
• project routers
• project memory under Assets/AIOutput/ProjectMemory/
• project outputs under Assets/AIOutput/
• repo-level mutable AI state under AIOutput/

Practical rule:

• AIRoot defines reusable public-safe building blocks
• the host repo decides how those blocks are actually routed at runtime

First Mental Model

Think in three layers:

1. AIRoot/ Public reusable layer.
2. Host repo routing and mutable state Repo router, host-local overlays, setup wrappers, reports, registry.
3. Project-local truth Project routers, project memory, and project outputs.

flowchart TD
    A[Host Repo Router] --> B[AIRoot public core]
    B --> C[Optional host-local private overlays]
    C --> D[Project router]
    D --> E[Project memory]
    E --> F[Relevant prior outputs]

Loading

The important boundary is simple:

• reusable and public-safe -> keep it in AIRoot
• host-private or mutable -> keep it outside AIRoot
• project-specific durable truth -> keep it in project-local memory

Start Here

Use this order:

1. If an AI agent can open the repo locally, start with Operations/Setup/AI_ASSISTED_SETUP_PROMPT.md.
2. If no AI tool is ready yet, start with Operations/Setup/AI_EASY_SETUP.md.
3. Use Operations/Setup/SETUP_INDEX.md only for script-level bootstrap details.
4. Use Operations/README.md after setup to browse public operation and tool surfaces.
5. Use INTEGRATION.md when wiring AIRoot into a real host repo.

Post-validation rule:

• do not call the host xuunity-ready only because files were created
• the setup flow should pass the matching --check path
• the expected routing files and AIOutput/Registry/ status files must exist

After setup:

• generic product-facing usage -> Operations/AI_PRODUCT_FACING_GUIDE.md
• operator rules -> Operations/AI_PROTOCOL_HANDBOOK.md
• topology -> Visuals/AI_PROTOCOL_VISUAL_MAP.md

What You Get

Public Protocol Core

• Modules/XUUnity/ Public-safe execution protocol for Unity mobile engineering.

Inside xuunity you get:

• roles
• tasks
• reviews
• utilities
• skills
• platforms
• decision-support knowledge

Reusable Operations

• Operations/ Setup guides, handbooks, exporter workflows, and generic operational docs.

Main entrypoints:

• README.md
• AI_EASY_SETUP.md
• AI_ASSISTED_SETUP_PROMPT.md
• AI_SETUP.md
• SETUP_INDEX.md
• AI_PROTOCOL_HANDBOOK.md

XUUnity Light Unity MCP

• Operations/XUUnityLightUnityMcp/ Public reusable lightweight Unity MCP path for xuunity.

Primary MCP entrypoints:

• overview: Operations/XUUnityLightUnityMcp/README.md
• public wrapper: Operations/XUUnityLightUnityMcp/xuunity_light_unity_mcp.sh
• public init: Operations/XUUnityLightUnityMcp/init_xuunity_light_unity_mcp.sh

Key MCP docs:

• design: Operations/XUUnityLightUnityMcp/DESIGN.md
• integration: Operations/XUUnityLightUnityMcp/AI_INTEGRATION.md
• agent workflows: Operations/XUUnityLightUnityMcp/AGENT_WORKFLOWS.md
• smoke contract: Operations/XUUnityLightUnityMcp/SMOKE_TESTS.md
• roadmap: Operations/XUUnityLightUnityMcp/ROADMAP.md
• continuation: Operations/XUUnityLightUnityMcp/CONTINUATION.md
• public reports index: Operations/XUUnityLightUnityMcp/Reports/README.md

Reusable MCP assets:

• scenario templates: Operations/XUUnityLightUnityMcp/templates/scenarios/
• smoke runners: Operations/XUUnityLightUnityMcp/templates/smoke/
• Unity package source: Operations/XUUnityLightUnityMcp/packages/com.xuunity.light-mcp/

Visuals And Design

• Visuals/ Architecture and protocol maps.
• Design/ Long-form design notes and system documents.
• Roadmaps/ Execution plans, roadmap state, and milestone-level direction.

Templates And Scripts

• Templates/ Reusable templates for routers, reviews, and operational workflows.
• scripts/ Bootstrap helpers for attaching AIRoot to a host repo.

Main bootstrap entrypoints:

• AIRoot/AIROOT_SETUP.md
• AIRoot/Operations/Setup/AIROOT_SETUP_PROTOCOL.md
• AIRoot/scripts/init_ai_topology.sh
• AIRoot/scripts/init_ai_repo.sh
• AIRoot/scripts/init_ai_project.sh

Design placement rules:

• cross-cutting public designs -> AIRoot/Design/
• public tool-specific or surface-specific designs -> AIRoot/Operations/<ToolOrSurface>/Designs/
• host-local or private designs -> host repo AIOutput/Operations/Design/

Repository Map

• Modules/ Public execution protocols and reusable prompt behavior.
• Operations/ Generic setup, onboarding, export, and handbook docs.
• Visuals/ Architecture maps and diagrams.
• Design/ Protocol and system design documents.
• Roadmaps/ Planning and execution direction.
• Templates/ Reusable templates for adoption and maintenance.
• scripts/ Bootstrap tooling for repo and project setup.

How xuunity Fits

xuunity is the main public protocol family in AIRoot.

Use it for:

• bug fixing
• refactoring
• feature development
• code review
• SDK integration and SDK review
• native plugin work
• performance and runtime stability
• product-facing implementation explanations
• protocol-system maintenance

Canonical public entrypoints:

• module overview: Modules/XUUnity/README.md
• command handbook: Operations/AI_PROTOCOL_HANDBOOK.md
• visual map: Visuals/AI_PROTOCOL_VISUAL_MAP.md

Integration Model

Attach AIRoot to a real host repo and let the host own runtime routing.

Recommended host shape:

HostRepo/
  Agents.md
  AIRoot/
  AIOutput/
  ProjectA/
    Agents.md
    Assets/
      AIOutput/
        ProjectMemory/

Use:

• AI_EASY_SETUP.md for the simplest first-use path
• AI_ASSISTED_SETUP_PROMPT.md when an AI agent should drive setup
• AIROOT_INSTALL_RETRO_PROMPT.md when setup failed or needed manual recovery
• Operations/README.md for public operation and tool surfaces after bootstrap
• INTEGRATION.md for the host contract
• SETUP_INDEX.md for setup entrypoints

Do not:

• add AIRoot/Agents.md
• create fake project memory under AIRoot
• treat AIRoot as a replacement for a host repo router

Placement Rules

Use AIRoot for:

• reusable public-safe protocol behavior
• reusable setup and onboarding docs
• reusable templates
• public-safe diagrams and design notes

Do not use AIRoot for:

• host-private protocol families
• host-level mutable state
• project-specific memory
• project-specific generated outputs
• the only source of truth for active runtime behavior

Main Documents

• design:
  • XUUNITY_SKILLS_SYSTEM_DESIGN.md
  • XUUNITY_PRODUCT_PROTOCOLS_DESIGN.md
  • XUUNITY_EXTERNAL_REPOS_DESIGN.md
  • XUUNITY_UPSTREAM_SUBMODULE_DESIGN.md (archived — legacy)
• roadmap:
  • AI_AUTOMATION_ROADMAP.md
  • AI_AUTOMATION_EXECUTION_PLAN.md
• visuals:
  • AI_PROTOCOL_VISUAL_MAP.md
• operations:
  • AI_EASY_SETUP.md
  • AI_ASSISTED_SETUP_PROMPT.md
  • AI_PROTOCOL_HANDBOOK.md
  • AI_SETUP.md
  • SETUP_INDEX.md
  • AI_PRODUCT_FACING_GUIDE.md
  • AI_EXTERNAL_REPO_PATH_MIGRATION_RUNBOOK.md
  • XUUNITY_KNOWLEDGE_EXTRACTION_EVALUATION.md
• integration:
  • INTEGRATION.md