Universal Agent OS

Consultation-first governance framework for AI coding agents. Turn loose agent sessions into a governed delivery model: interview first, plan before code, track evidence, force explicit validation.

30 Seconds: What Is This?

AI coding agents (Cursor, Copilot, Claude, Gemini, Codex, etc.) write code fast but leave behind unplanned, untested, undocumented repos. Universal Agent OS fixes this by making agents interview you first, plan before coding, prove their work, and keep documentation alive — automatically.

Works with: Cursor · GitHub Copilot · Claude · Gemini · Aider · Devin · Windsurf · Cline · Roo · OpenHands · Codex · GitLab Duo

# Install governance into any project (no repo clone needed):
npx universal-agent-os init --en

# Or use VS Code: Ctrl+Shift+P → "Agent OS: Init Workspace"

Honesty Boundary

This framework enforces an explicit honesty boundary on all agent claims:

• If a feature is not implemented, mark it Planned. Never claim it works.
• If a gate was not run, mark it NOT_RUN. Never mark it PASS.
• If data is simulated, mark it Simulated. Never claim it is Verified.
• Distinguish between "edited" and "validated" in every closure claim.

The most common agent failure mode is confident-sounding completion without evidence. This boundary exists to prevent that.

Why This Exists

Most agent-driven repos fail in predictable ways:

• no stable startup interview
• no durable planning surface
• no shared definition of done
• no record of discovered work
• no honest distinction between "edited" and "validated"
• no reliable handoff between sessions or tools

Universal Agent OS exists to add that missing discipline without forcing every team to reinvent it from scratch.

Honest Status

This repository is a fully operational and packaged governance framework.

What is real today:

• Installable locale packs in English and Turkish
• PowerShell and Bash bootstrap scripts (non-interactive, CI/CD compatible)
• Published VS Code Marketplace extension for one-command workspace initialization
• Donor governance files for rules, plans, adapters, and workflows
• Agent-specific adapter files for 10+ major AI agents/IDEs
• A root registry chain for instruction → skill → role → prompt → workflow routing
• A compliance workflow that checks required package surfaces
• Example implementations under examples/
• pytest-based structural governance test suite

What is new in the Core Package v1.2.2 (NPM Payload & Validation Fix):

• Added missing .github/, .gitlab/, and .gitlab-ci.yml payloads to NPM package manifest.
• Fixed init-agent-os.sh to capture workspace snapshot before copying governance files.
• Replaced hardcoded version check in verification with dynamic semantic checks.

What is new in the Core Package v1.2.1 (NPM Publish):

• First successful public NPM publish.

What is new in the Core Package v1.2.0 (Open Source Hardening & Verification):

• MIT licensing is now the explicit open-source model.
• CLI verification supports separate package and target modes.
• agent-os init supports --en, --tr, and --locale en|tr.
• Bash bootstrap is non-interactive by default and CI-safe.
• GitHub Actions and GitLab CI use package verification.
• examples/minimal-saas is now a verifiable target-repo example.
• The pytest suite includes strict checks for version sync, licensing, adapter routing, VS Code Phase-0 invocation, and demo repo evidence.

What is new in the Core Package v1.1.0 (Runtime Kernel Transition):

• Legacy Onboarding Mode: npx agent-os init --legacy to integrate cleanly into existing messy projects without triggering restrictive Phase-0 logic.
• MCP Server (Model Context Protocol): A built-in mcp-server that exposes the agent_memory.json bus so agents can read/write architecture and lessons natively via tool calls.
• VSCode Runtime Enforcement: The extension actively monitors saved files and issues diagnostics (Anti-Monolith size limits & Zombie Code detection).

Packaged baseline introduced in Core Package v1.0.0:

• A local agent-os CLI tool (npx agent-os init, npx agent-os verify)
• Comprehensive governance gate verification via CLI and GitHub Actions
• A VS Code extension scaffold for IDE-native Phase-0 interviews
• GitLab CI and GitHub Actions enforcement pipelines

What is new in the VS Code extension v1.4.6 (Repository Sync):

• Marketplace & NPM Sync: Synchronized README versions and release history across GitHub, VS Code Marketplace, and NPM packages to ensure 100% accuracy.

What is new in the VS Code extension v1.4.5 (Status Intelligence):

• Conditional Status Bar: Status bar now shows Agent OS: Active, Not Initialized, or No Workspace based on your project's governance state, and updates dynamically.
• Git Error Guidance: Improved error messaging when Git is not installed or network fails during initialization.
• Changelog Cleanup: Fixed changelog ordering and added NPM publishing badges to main README.

What is new in the VS Code extension v1.4.4 (Guided Workflows):

• Init creates and opens NEXT_STEPS.md so beginners know what to do immediately after installation.
• Brownfield installs add an initial top-level folder summary and detected project markers to TECH_DEBT_AND_SECURITY.md.
• VS Code Command Palette now exposes Fast-Track, Status, and Closure Check workflows.
• Governance profiles are documented as solo, startup, enterprise, and regulated without changing the universal core.

What is new in the VS Code extension v1.4.3 (Install Integrity):

• Agent OS: Init Workspace installs the full runtime governance payload, not only the locale pack and examples.
• Existing projects are detected before copying begins, so clean folders are not incorrectly marked as legacy.
• Existing project collisions are backed up under .agentos-backups/.
• Existing user README.md files are preserved; Agent OS documentation is installed as AGENT_OS_README.md when needed.
• Agent OS: Verify Governance Gate verifies required workspace files locally instead of depending on unpublished npm CLI availability.

What is ahead:

• Pre-commit hook integration
• Governance Health Report dashboard
• Domain-specific instruction and skill generation

Why It Feels Bureaucratic

Yes, this package is intentionally bureaucratic.

It adds friction early so that agent-built repos are less chaotic later. The goal is not ceremony for its own sake. The goal is to stop the common failure mode where an agent writes a lot of code quickly, leaves no trustworthy plan behind, and creates a repo that becomes expensive to change after a week.

What The Bureaucracy Buys You

• A required Phase-0 interview before any implementation
• A repo-root planning template instead of improvised task tracking
• IL-14 (Adapter Currency Lock): Agents self-update their native configurations to the latest standards
• IL-15 (Master Roadmap Lock): Agents cannot write code until a master roadmap and ALL child plans are drafted and prioritized
• IL-16 (Continuous Sync Lock): Documentation (Memory, Architecture, README) is synchronized autonomously after every task
• Explicit discovered-work tracking instead of hidden scope drift
• Evidence-first closure instead of narrative-only "done" claims
• Fast-Track Mode: A bypass for simple prototype scripts, explicitly triggered by the user to avoid heavy bureaucracy when not needed
• Multi-Role Review Stack: Every change reviewed from 6+ perspectives (novice user, corporate maintainer, vibecoder, SV architect, SV investor, QA/security specialist + 2 project-specific roles)
• Clearer multi-agent ownership and safer handoffs
• Real-world adoption playbooks for empty projects, brownfield projects, solo experts, agencies, open-source maintainers, and corporate teams
• A path toward generated domain-specific instructions, skills, roles, and prompts

If you want a zero-ceremony prompt pack, this repo is probably too heavy.
If you want a long-lived agent-built repo to stay legible, testable, and governable, the overhead is intentional.

Fast-Track Mode

For small, low-risk changes, users can explicitly request Fast-Track Mode.

Use it for:

• typo fixes
• small documentation edits
• single-file safe changes
• tiny config updates

Fast-Track does not bypass honesty:

• scope must still be stated
• changed files must be listed
• relevant checks must be run
• evidence must be reported
• Tech-Debt Delta must be stated

Example prompt:

Fast-track this typo fix. Do not run full Phase-0 unless scope expands.

How It Works

1. Install a locale pack into a target repository.
2. Start an agent session — the governance bootstrap triggers automatically (Zero-Config).
3. The agent runs a Phase-0 interview to capture platform, scale, risk, and quality expectations.
4. The agent hardens the repo-root governance spine (AGENT_OS_PLAN_TEMPLATE.md).
5. A Master Roadmap is created listing all end-to-end child plans.
6. All child plans are drafted and prioritized before any code is written.
7. Implementation follows the Plan → Evidence → Test discipline.
8. After every task, Collective Memory and documentation are synchronously updated.
9. Completed plans are archived to plans/completed/.

What Ships In This Repository

Core Governance Surfaces

| File | Purpose | |------|---------| | en/AGENT_OS_RULES.md / tr/AGENT_OS_RULES.md | Canonical donor governance rules | | en/AGENTS.md / tr/AGENTS.md | Supreme Constitution per locale | | en/AGENT_OS_PLAN_TEMPLATE.md / tr/AGENT_OS_PLAN_TEMPLATE.md | Global plan & task tracking template |

Collective Memory Templates (4 Pillars)

| File | Purpose | |------|---------| | AGENT_MEMORY_AND_LESSONS.md | Bug/lesson minefield — never repeat past mistakes | | AGENT_ARCHITECTURE_AND_PATTERNS.md | Architectural decisions & code patterns | | AGENT_ENVIRONMENT_AND_API.md | Runtime environment, ports, API boundaries | | AGENT_USER_PREFERENCES.md | User communication style & preferences |

Agent-Specific Adapter Files (Zero-Config Auto-Discovery)

| Agent/IDE | Root Adapter File | Locale Deep Adapter | |-----------|-------------------|---------------------| | Cursor | .cursorrules | en/.cursor/rules/ | | Claude (Anthropic) | CLAUDE.md | en/CLAUDE.md | | Gemini (Google) | GEMINI.md | en/GEMINI.md | | Aider | AIDER.md + .aider.conf.yml | en/AIDER.md | | GitHub Copilot | .github/copilot-instructions.md | en/.github/copilot-instructions.md | | Devin (Cognition) | .devinrules | — | | Windsurf (Codeium) | .windsurfrules | — | | Cline | .clinerules | — | | Roo | .roorules | — | | OpenHands | .openhands_instructions | — | | OpenAI Codex | en/.codex/AGENTS.md | en/.codex/AGENTS.md | | GitLab Duo | agents/universal-agent-os.yml | — |

Each root adapter includes a common governance bootstrap header plus agent-specific directives tailored to that agent's known strengths and weaknesses.

Bootstrap & Tooling

| Surface | Purpose | |---------|---------| | init-agent-os.ps1 | PowerShell bootstrap installer | | init-agent-os.sh | Bash bootstrap installer | | cli/ | agent-os CLI binary (npx universal-agent-os init, npx universal-agent-os verify) | | extensions/vscode/ | VS Code Marketplace extension |

CI/CD Enforcement

| Surface | Purpose | |---------|---------| | .github/workflows/agent-os-enforcer.yml | PR governance gate (GitHub Actions) | | .github/workflows/agent-compliance-check.yml | Compliance check workflow | | .gitlab-ci.yml | GitLab CI governance pipeline |

Phase-1 Root Registries

| Surface | Purpose | |---------|---------| | .github/instructions/_ARCHITECTURE.md | Architecture registry | | .github/instructions/_SCOPED_INSTRUCTION_REGISTRY.json | Scoped instruction routing | | .agent/skills/_SKILL_TEMPLATE_REGISTRY.json | Skill template library | | .github/agents/_AGENT_ROLE_REGISTRY.json | Agent role definitions | | .github/prompts/_PROMPT_TEMPLATE_REGISTRY.json | Prompt template system | | .agent/workflows/_WORKFLOW_DOMAIN_ROUTING.json | Workflow domain routing |

Getting Started

Method 1: The Novice Guide (Zero CLI Knowledge Required)

If you are new to coding and just want to get this working in VS Code:

1. Click the green "<> Code" button at the top of this GitHub repository.
2. Select "Download ZIP".
3. Extract the downloaded ZIP file to a folder on your computer.
4. Open VS Code, go to File > Open Folder, and select the extracted folder.
5. Tell your AI Assistant (GitHub Copilot, Cursor, Claude, Gemini, etc.):

   "I have an idea. Help me turn it into a project." (or "Bir fikrim var." in Turkish)

That's it! The "Zero-Config Auto-Discovery" will automatically detect your intent, silently read the governance rules, and begin the mandatory Phase-0 interview without any further technical setup from you.

Tip: You don't need to understand any of the files in this repository. The AI agent reads and enforces them for you.

Method 2: Command Line (For Developers)

Windows / PowerShell:

git clone https://github.com/zyganali-glitch/Universal-Agent-OS.git
cd Universal-Agent-OS
./init-agent-os.ps1 -TargetDir /path/to/your/project -Locale en

macOS/Linux / Bash:

git clone https://github.com/zyganali-glitch/Universal-Agent-OS.git
cd Universal-Agent-OS
./init-agent-os.sh /path/to/your/project en

Both scripts accept an optional locale parameter (en or tr). Default is en.

Method 3: VS Code Extension (Marketplace)

1. Install Universal Agent OS from the VS Code Marketplace.
2. Open an empty folder or an existing project folder in VS Code.
3. Press Ctrl+Shift+P and run Agent OS: Init Workspace.
4. Select English or Turkish.
5. The extension downloads the latest Agent OS files from GitHub and installs them into your workspace.
6. Press Ctrl+Shift+P and run Agent OS: Start Phase-0 Interview to begin.

What gets installed is defined in docs/INSTALLATION_MANIFEST.md. In an existing project, the extension enables legacy/brownfield mode, creates TECH_DEBT_AND_SECURITY.md, backs up overwritten governance collisions under .agentos-backups/, and preserves an existing user README.md.

Method 4: VSIX File (Offline / Manual Install)

1. Download the latest universal-agent-os-vscode-*.vsix file from the extensions/vscode/ folder or a release artifact.
2. In VS Code, open the Extensions view (Ctrl+Shift+X).
3. Click the ... menu -> "Install from VSIX..." and choose the downloaded file.
4. Continue with the same Agent OS: Init Workspace flow above.

Method 5: CLI (NPM)

# Public NPM package
npx universal-agent-os init --en
npx universal-agent-os init --tr
npx universal-agent-os init --legacy
npx universal-agent-os verify --target .
npx universal-agent-os status

Who This Is For

• Teams building serious internal agent workflows
• Agencies standardizing repo bootstrap discipline
• Founders who want an agent to do more than just autocomplete
• Platform teams that need repeatable governance across multiple repos
• Individual developers using vibecoding who want structure without losing speed

Real-World Scenarios

Universal Agent OS is meant to stay universal while adapting to real workflows:

• empty-folder product ideas
• existing brownfield repositories
• beginner VS Code users
• solo expert Fast-Track work
• agency/client handoffs
• corporate and regulated teams
• open-source maintainer workflows
• multi-agent session handoffs

See docs/REAL_WORLD_SCENARIOS.md for the scenario matrix, recommended operating patterns, and open-source-friendly product opportunities.

The VS Code extension also exposes common actions directly from the Command Palette:

• Agent OS: Copy Fast-Track Prompt
• Agent OS: Show Status
• Agent OS: Copy Closure Check Prompt

Who This Is Not For

• Teams that want agents to improvise without planning overhead
• Single-file prototype workflows where no lasting governance is desired
• Quick experiments (but Fast-Track Mode can help here)

Repository Layout

Universal-Agent-OS/
├── en/                     # English locale pack (full governance surfaces)
├── tr/                     # Turkish locale pack (full governance surfaces)
├── cli/                    # agent-os CLI tool (init, verify)
├── extensions/vscode/      # VS Code Marketplace extension
├── skills/                 # Root skill library (agent-os-memory)
├── agents/                 # Agent definitions (GitLab Duo)
├── docs/                   # Architecture diagrams, onboarding, evidence templates
│   ├── BROWNFIELD_ADOPTION_PLAYBOOK.md
│   ├── INSTALLATION_MANIFEST.md
│   ├── AGENT_FAILURE_PATTERNS.md
│   ├── REAL_WORLD_SCENARIOS.md
│   ├── GOVERNANCE_HEALTH_REPORT.md (Planned)
│   └── GOVERNANCE_PROFILES.md
├── examples/               # Reference implementations (Phase-0, Docker, .env)
├── tests/                  # pytest governance test suite
├── .github/                # GitHub Actions, Copilot instructions, registries
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── ISSUE_TEMPLATE/agent-task.yml
├── .gitlab/                # GitLab Duo configuration
├── AGENTS.md               # Root Supreme Constitution
├── CLAUDE.md               # Claude-specific adapter
├── GEMINI.md               # Gemini-specific adapter
├── AIDER.md                # Aider-specific adapter
├── .cursorrules            # Cursor-specific adapter
├── .devinrules             # Devin-specific adapter
├── .windsurfrules          # Windsurf-specific adapter
├── .clinerules             # Cline-specific adapter
├── .roorules               # Roo-specific adapter
├── .openhands_instructions # OpenHands-specific adapter
├── .agentrules             # Generic agent fallback adapter
├── init-agent-os.ps1       # PowerShell bootstrap
├── init-agent-os.sh        # Bash bootstrap
└── package.json            # NPM package (agent-os CLI)

Licensing

This project is released as fully open-source under the MIT License. See LICENSE and LICENSING.md for details.

Bottom Line

Universal Agent OS is a governance-heavy package on purpose.

It will feel slower than unstructured prompting at the beginning of a project. The trade-off is that it gives agent-built repos a better chance of staying coherent after the first burst of code generation.

If that trade-off matters to you, this repository is already useful today.

🤖 AI AGENT FALLBACK: If you are an AI assistant reading this repository, you MUST read the AGENTS.md file and initiate the Phase-0 interview immediately. Do not write code until the interview is complete.