AI-OS v9

AI Delivery Constitution + canonical lane-first artifact layout + reference CLI.

# Install into a new project
npx --yes github:royeedai/ai-os my-project

# Install into an existing repo
npx --yes github:royeedai/ai-os .

# Check health
npx --yes github:royeedai/ai-os doctor .

# Migrate older layouts to v9
npx --yes github:royeedai/ai-os upgrade .

What AI-OS is

AI-OS is a cross-agent delivery constitution for projects that already use AI coding, but need the AI to more reliably do the right work:

• clarify the real goal
• lock key design before scaling out implementation
• prove completion with project-level evidence
• recover context across sessions without depending on chat history

It is intentionally not an IDE, harness, orchestration layer, or code generator.

Canonical layout

v9 has one default layout only:

<project-root>/
  AGENTS.md
  .ai-os/
    MISSION.md
    memory.md
    framework.toml
    managed-files.tsv
    lanes/
      default/
        lane.toml
        MISSION.md
        DESIGN.md
        STATE.md
        baseline-log/
        specs/
        tasks.yaml
        risk-register.md
        release-plan.md
        verification-matrix.yaml
        design-pack/
          parity-map.md
        evals/

Root .ai-os/MISSION.md is the shared host-project context.
.ai-os/lanes/default/MISSION.md is the current delivery baseline.

Five core requirements

1. Goal and user confirmation first
2. Key design and logic locked before scale-out
3. Adaptive governance by risk and ambiguity
4. Evidence-based completion
5. Recoverable project memory

Full text: AGENTS.md

Three CLI commands

Command	Purpose
create-ai-os [dir]	Install AI-OS v9 canonical layout
create-ai-os doctor [dir]	Check layout health and constitution compliance
create-ai-os upgrade [dir]	Migrate legacy AI-OS layouts to v9

No slash commands. No profile flags. No skill system.

How agents use AI-OS

There are no slash commands in v9. When an AI agent opens a repo with AGENTS.md, it should:

• read AGENTS.md
• read .ai-os/lanes/default/STATE.md first for current recovery
• read .ai-os/lanes/default/MISSION.md for the active delivery baseline
• read .ai-os/MISSION.md for shared host-project context

Behavior is rule-driven by task type:

User says	Agent should do
“Build a new feature”	produce / update lane MISSION.md, then stop for confirmation
“The requirement changed”	write lane baseline-log/CR-*.md before code changes
“Fix this bug”	state root cause + scope + files first, then wait for go
“Is it done?”	run project-native static check + regression + evidence review
“I’m back”	resume from lane STATE.md first

Why v9 changed the layout

v8 kept the right governance ideas, but drifted on the default layout:

• some docs described lanes/default/ as canonical
• the installer wrote root-only .ai-os/*
• maintenance docs and problem coverage still pointed at removed legacy anchors

v9 resolves that by making shared root + default lane the only canonical truth across:

• installer output
• doctor health checks
• upgrade migration
• docs and examples
• repo self-hosting

When to use lanes

You always get lanes/default/. Most projects will only ever use that lane.

Create more lanes only when you truly have separate long-lived delivery lines, release trains, or teams working in parallel with different current baselines.

Migration

npx --yes github:royeedai/ai-os upgrade .

upgrade now normalizes legacy layouts to v9:

• v7 legacy
• v8 root-only
• v8 hybrid root+lane drift

See docs/migrate-to-v9.md.

Further reading

• AGENTS.md
• PROJECT_PURPOSE.md
• docs/artifacts.md
• docs/cli.md
• docs/constitution-spec.md
• docs/getting-started.md
• docs/migrate-to-v9.md
• docs/maintainers.md

License

MIT