AgentOrchestrator

Level-0 control-plane OS for coding-agent governance.

Purpose

This repository defines the shared governance model, schemas, templates, and tooling used to bootstrap and coordinate coding-agent workflows across multiple repositories. It does not host product code.

Directory Structure

Directory	Purpose
agent-os/workflow/	Authoritative workflow model, lifecycle, taxonomy, portability, Git policy
agent-os/schemas/	Machine-readable contracts (PLAN schema)
agent-os/templates/	Canonical templates for repo-local and workspace governance files
agent-os/scripts/	Deterministic tooling: validation, rendering, bootstrap, sync
agent-os/prompts/	Shared prompt asset contracts and lifecycle guidance
agent-os/skills/	Reusable skill packaging contracts and compatibility guidance
docs/design/	Non-authoritative design and reference material

Governance Files

File	Role
AGENTS.md	Workflow authority and operating rules
ARCHITECTURE.md	Structural constraints and boundary rules
PLAN.yaml	Active execution tracking (source of truth)
PLAN.md	Human-readable plan view (generated)
PLAN.dot	Graph plan view (generated)

Quick Start

Configure the Python environment

Copy .env.example to .env and set AGENT_PYTHON for your workstation:

cp .env.example .env
# Edit .env — set AGENT_PYTHON to your local Python command, e.g.:
#   AGENT_PYTHON="conda run -n nn-2 python"
#   AGENT_PYTHON="python3"
#   AGENT_PYTHON="/path/to/venv/bin/python"

.env is gitignored and never committed. Scripts source it automatically. For manual commands, source it first: source .env

Install runtime dependencies

$AGENT_PYTHON -m pip install -r requirements.txt

Install development and test tooling

$AGENT_PYTHON -m pip install -r requirements-dev.txt

Validate a plan

$AGENT_PYTHON agent-os/scripts/validate-plan.py PLAN.yaml --schema agent-os/schemas/plan.schema.json

Render plan views

$AGENT_PYTHON agent-os/scripts/render-plan.py PLAN.yaml

Run script tests

$AGENT_PYTHON -m pytest -q

Run local quality gates

bash agent-os/scripts/run-gates.sh

Bootstrap a new repository

bash agent-os/scripts/bootstrap-repo.sh --owner <name> --ref <branch|tag> <target-path>

The bootstrap also writes .githooks/commit-msg into the target repository. It also writes .github/copilot-instructions.md as a thin repo-level runtime entrypoint; canonical governance still lives in AGENTS.md, ARCHITECTURE.md, and PLAN.yaml. Enable it with:

git -C <target-path> config core.hooksPath .githooks
chmod +x <target-path>/.githooks/commit-msg

Sync workspace runtime files

bash agent-os/scripts/sync-workspace.sh <workspace-root-path>

Testing and Gates

The Python environment is configured per workstation via AGENT_PYTHON in .env.

• Python tests: $AGENT_PYTHON -m pytest -q
• Gate runner: bash agent-os/scripts/run-gates.sh (sources .env automatically)
• The gate runs Ruff, mypy, Python compile checks, pytest, and ShellCheck when ShellCheck is available on the local machine.
• requirements.txt stays runtime-only; development/test tooling lives in requirements-dev.txt.

sync-workspace.sh materializes runtime files from the current local control-plane checkout. It does not pull from the remote automatically. It currently renders only the workspace-scoped runtime entrypoints (AGENTS.md, CLAUDE.md, .codex). If you want the latest origin/main first, run:

git -C /path/to/AgentOrchestrator pull --ff-only origin main
bash agent-os/scripts/sync-workspace.sh <workspace-root-path>

Enable local commit message guard

git config core.hooksPath .githooks
chmod +x .githooks/commit-msg

The local commit-msg hook enforces:

<type>(<scope>): <description>

and exactly one footer line of the form:

Refs: <PLAN item IDs>, <commit_group ID>

Regexes:

• ^([a-z]+)\(([a-z0-9._/-]+)\): .+$
• item IDs: [A-Z]+[1-9][0-9]*\.[1-9][0-9]*\.[1-9][0-9]*[a-z]?
• commit groups: cg[1-9][0-9]*

You can test it quickly with:

printf "docs(workflow): valid title\n\nRefs: D1.1.1, cg1\n" > /tmp/good-msg.txt
.githooks/commit-msg /tmp/good-msg.txt

printf "docs(workflow): missing refs\n\n" > /tmp/bad-msg.txt
.githooks/commit-msg /tmp/bad-msg.txt

Three-Layer Model

• Level 0 (this repository): central control plane — shared workflow, schemas, templates, scripts
• Level 1: workspace runtime materialization — generated from Level-0 templates by sync-workspace.sh for workspace-scoped runtimes
• Level 2: repository-local governance — bootstrapped from Level-0 templates by bootstrap-repo.sh

Runtime entrypoint artifacts remain thin pointers only. In this repository:

• CLAUDE.md and .codex are workspace/runtime entrypoints
• .github/copilot-instructions.md is the repo-level Copilot entrypoint
• AGENTS.md remains the portable repo-level entrypoint for Kilo in v1

License

See LICENSE.