org-agentic-toolkit 1.0.0

Governance infrastructure that compiles and validates organization-level agent rules

Org Agentic Toolkit (OAT)

Governance infrastructure that compiles and validates organization-level agent rules for all projects in an org.

Overview

The Org Agentic Toolkit (OAT) defines, compiles, and distributes the authoritative agent rules for all projects within an organization. It ensures every project inherits org rules by construction, allows optional personal overlays without weakening org authority, and produces deterministic, auditable agent instructions.

Features

• Single org-wide agentic constitution: Enforce consistent rules across all projects
• Explicit inheritance: Projects explicitly declare which skills and personas they use
• Personal overlays: Optional developer-specific preferences (lowest precedence)
• Deterministic compilation: Same inputs produce same output byte-for-byte
• IDE integration: Output to IDE-specific configuration files (Cursor, Windsurf, etc.)
• Validation: Comprehensive validation of configuration and referenced files

Installation

From Source (with uv and pyproject)

git clone <repository-url>
cd org_agentic_toolkit

# Install in editable mode using uv, based on pyproject.toml with dev dependencies
uv pip install -e ".[dev]"

This uses uv following dependencies declared in pyproject.toml, with the package installed as a development-only dependency.

---

Inspiration:
This project is partly inspired by nAItmare, an open-source repository for centralizing multi-agent standards.

Requirements

• Python 3.12+
• pyyaml>=6.0
• click>=8.0

Optional dependencies (for development):

• pytest>=9.0.0
• pytest-cov>=7.0.0
• jsonschema>=4.0.0 (for schema validation)
• watchdog>=6.0.0 (for watch mode)

Quick Start

1. Initialize a Project

cd your-project
oat init project --org-root ../org-agentic-toolkit

This creates:

• AGENTS.md - Entry point for agents
• .agent/inherits.yaml - Project configuration
• AGENTS.md - Entry point for agents
• .agent/inherits.yaml - Project configuration
• .agent/project.md - Project-specific rules

2. Initialize Org Root (Optional but Recommended)

To create a new organization root repository:

mkdir my-org
cd my-org
oat init org

This creates the full structure for an organization's agent rules, including a .oat-root marker file.

Organization Root Discovery:

• The .oat-root file is the primary indicator for an organization root
• OAT automatically discovers org roots by walking up the directory tree looking for .oat-root
• If .oat-root is not found, it falls back to checking for .agent/memory/constitution.md
• You can also specify the org root path in .agent/inherits.yaml or via the OAT_ROOT environment variable

3. Initialize Personal Overlay (Optional)

To create a personal overlay for your own preferences:

oat init personal

2. Configure Your Project

Edit .agent/inherits.yaml to specify which skills and personas your project uses:

org_root: ../..
skills:
  universal:
    - git
    - test
    - db
  languages:
    python:
      - django
      - pytest
personas:
  - backend-developer
  - tech-lead
target_agents:
  - cursor
  - windsurf

3. Compile Agent Instructions

oat compile

This produces AGENTS.compiled.md with all rules merged in the correct precedence order.

4. Validate Configuration

oat validate

Checks that all referenced files exist and configuration is valid.

CLI Commands

oat compile

Compile agent instructions from org rules, project rules, and personal overlay.

Options:

• --out <path>: Override output path (default: AGENTS.compiled.md)
• --target <name>: Compile for specific IDE (e.g., cursor, windsurf)
• --no-personal: Ignore personal overlay
• --print: Print compiled content to stdout
• --hash: Include content hash in output
• --diff: Show changes since last compilation
• --include-skill <name>: Additionally include a skill
• --exclude-skill <name>: Exclude a skill from manifest
• --include-persona <name>: Additionally include a persona
• --exclude-persona <name>: Exclude a persona from manifest
• --repo <path>: Explicit repo root path

Examples:

# Basic compilation
oat compile

# Compile for Cursor IDE
oat compile --target cursor

# Compile with hash
oat compile --hash

# Print to stdout
oat compile --print

oat validate

Validate repository configuration and referenced files.

Options:

• --repo <path>: Explicit repo root path
• --strict: Treat warnings as errors
• --json: Output JSON format

Examples:

# Basic validation
oat validate

# Strict validation
oat validate --strict

# JSON output
oat validate --json

oat doctor

Show diagnostic information about the current repository configuration.

Options:

• --json: Output JSON format

Example:

oat doctor

Output includes:

• Repo root and org root paths
• Entry point location
• Constitution version
• Memory files loaded
• Skills and personas from manifest
• Teams referenced
• Project rules location
• Personal overlay status
• Available but not included items

oat init project

Initialize a project repository with agentic toolkit configuration.

Options:

• --org-root <path>: Explicit org root path
• --force: Overwrite existing files
• --suggest: Suggest skills/personas based on project files

Examples:

# Basic initialization
oat init project

# With suggestions
oat init project --suggest

# With explicit org root
oat init project --org-root ../org-agentic-toolkit

oat init org

Initialize an organization root repository.

Options:

• --name <name>: Organization name (default: "My Org")
• --force: Overwrite existing files

oat init personal

Initialize personal overlay directory.

Options:

• --path <path>: Override personal folder path
• --force: Overwrite existing files

Project Structure

Org Root

org-agentic-toolkit/
├── .oat-root                 # Discovery marker
├── AGENTS.md                 # Entry point
├── .agent/
│   ├── memory/
│   │   ├── constitution.md   # Immutable org rules
│   │   ├── general-context.md
│   │   ├── manifest.yaml
│   │   └── teams/           # Team-specific context
│   ├── skills/              # Atomic knowledge modules
│   │   ├── git.md
│   │   ├── test.md
│   │   └── [language]/      # Language-specific skills
│   ├── personas/            # Specialized personas
│   └── toolkit/             # Toolkit implementation
└── repos/                    # Project repositories

Project Repo

project-repo/
├── AGENTS.md                 # Entry point (optional)
└── .agent/
    ├── inherits.yaml         # Project configuration (required)
    └── project.md            # Project-specific rules (required)

Compilation Order

The compiled document follows strict precedence (highest to lowest):

1. Entry Point (AGENTS.md from repo)
2. Org Memory (constitution, general-context, teams)
3. Universal Skills (from inherits.yaml, in order)
4. Language/Stack Skills (grouped by language, in order)
5. Org Personas (from inherits.yaml, in order)
6. Project Rules (project.md)
7. Personal Overlay (optional, lowest authority)

Environment Variables

• OAT_ROOT: Explicitly set the org root path
• ORG_AGENTIC_TOOLKIT_ROOT_NAME: Control org root directory naming pattern
• AGENT_PERSONAL_FOLDER: Path to personal overlay directory (default: ~/.agent)

IDE Integration

The toolkit supports outputting to IDE-specific configuration files via the --target option:

oat compile --target cursor    # Outputs to .cursorrules
oat compile --target windsurf   # Outputs to .windsurfrules

Supported targets are defined in .agent/toolkit/targets.yaml.

Personal Overlay

Developers can maintain personal preferences in ~/.agent/ (or path specified by AGENT_PERSONAL_FOLDER):

~/.agent/
├── memory/
│   └── personal-context.md
├── skills/
│   └── personal-git.md
└── personas/
    └── me.md  # Team membership (gitignored)

Personal overlay has the lowest precedence and cannot override org rules.

Validation Rules

The validator checks:

• AGENTS.md exists (warning if missing)
• .agent/inherits.yaml exists and is valid (error if missing)
• skills and personas sections exist (error if missing)
• org_root resolves and contains constitution
• All referenced skills exist
• All referenced personas exist
• All referenced teams exist
• .agent/project.md exists (error in strict mode, warning otherwise)
• .agent/project.md exists (error in strict mode, warning otherwise)
• No forbidden constructs (absolute paths, etc.)

Validation automatically detects the context:

• Org Root: Checks .oat-root, constitution, manifest, etc.
• Personal Overlay: Checks personal context, me.md
• Project Repo: Checks inherits.yaml and inheritance

Examples

Example: Python Django Project

.agent/inherits.yaml:

org_root: ../..
skills:
  universal:
    - git
    - test
    - db
    - review-checklist
  languages:
    python:
      - django
      - pytest
personas:
  - backend-developer
  - tech-lead
teams:
  - platform
target_agents:
  - cursor

Example: Full-Stack JavaScript Project

.agent/inherits.yaml:

org_root: ../..
skills:
  universal:
    - git
    - test
  languages:
    javascript:
      - react
      - nodejs
      - jest
personas:
  - frontend-developer
  - backend-developer
  - tech-lead

Development

Running Tests

pytest

Project Structure

org_agentic_toolkit/
├── oat/                 # Main package
│   ├── cli.py           # CLI commands
│   ├── discovery.py     # Root discovery
│   ├── config.py        # YAML loading
│   ├── compiler.py      # Compilation engine
│   ├── validator.py     # Validation logic
│   ├── template_manager.py # Template manager
│   └── templates/       # Template files (package data)
├── tests/               # Test suite
├── pyproject.toml       # Package config
└── MANIFEST.in          # Package data config

License

MIT

Contributing

Contributions welcome! Please read the contributing guidelines and submit pull requests.