# Agent Governance Toolkit - Repository Instructions

## Project Overview

Agent Governance Toolkit is a multi-package OSS monorepo for runtime governance of AI agents:
policy enforcement, zero-trust identity, execution sandboxing, SRE, compliance, examples,
docs, demos, SDKs, and publishing pipelines.

Use this file for repository-wide routing. When you enter a subdirectory that has its own
`AGENTS.md`, that narrower file takes precedence.

## Repository Layout Status

This routing reflects the repo **as it exists today** while reserving room for approved language
SDK migrations. Language SDKs may live in **standalone top-level directories** at the repository
root. For contributor routing, treat `agent-governance-dotnet/`, `agent-governance-golang/`, and
`agent-governance-rust/` as the canonical standalone language homes.

Treat current paths as a **point-in-time representation**, not a permanent architecture promise.
When a standalone top-level implementation exists for a language, changes for that language should
go there rather than into the repo root or an older shared SDK path.

## Where Changes Belong

| Area | Path | Use it for |
|------|------|------------|
| Published Python packages | `agent-governance-python/` | First-party reusable Python packages and SDK surfaces meant for direct external consumption |
| Python runtime and product code | `*/` | Runtime code, applications, policy engines, trust, SRE, compliance, and other Python product surfaces that have not moved into the standalone package home |
| Current shared SDK paths | `agent-governance-python/agent-mesh/sdks/` | Public SDK APIs and language-specific packaging that still live in the shared layout today |
| Standalone language implementations | `agent-governance-python/`, `agent-governance-dotnet/`, `agent-governance-golang/`, `agent-governance-rust/`, and other `agent-governance-*` siblings | Top-level language-specific implementations at the repository root; use these as the canonical contributor-facing paths |
| Docs site | `docs/` | Reference docs, tutorials, architecture, package pages |
| Runnable examples | `examples/` | Self-contained integrations and worked examples |
| Interactive demos | `examples/demos/` | Live demos, dashboards, real-service walkthroughs |
| Release automation | `.github/workflows/` | GitHub Actions release, packaging, SBOM, provenance, and publishing automation |
| GitHub automation | `.github/` | CI, PR automation, issue templates, policy workflows |

## Routing Rules

1. Prefer the smallest correct scope for a change.
2. Put third-party integrations in `examples/` or `agent-governance-python/agentmesh-integrations/` before
   expanding core packages.
3. Put marketing or ecosystem references in docs only after the integration is real, attributable,
   and useful to users.
4. Keep `.github/` changes separate from feature work; they require extra security review.
5. If both a legacy shared path and a standalone top-level path exist, prefer the standalone
   top-level path for new work unless maintainers say otherwise. For Python package work, use
   `agent-governance-python/` as the canonical package home. For the approved .NET standalone
   migration, contributor guidance should point to `agent-governance-dotnet/` as the canonical
   path.

## OSS Contribution Expectations

- Read the nearest `AGENTS.md` before changing code in that area.
- Keep PRs scoped to the path described in the PR.
- Add or update tests for behavior changes, bug fixes, security fixes, and new public API surface.
- Attribute prior art in PR descriptions and docs when a design borrows from another project.
- Prefer examples and docs for low-risk ecosystem additions; prefer core package changes only when
  the project has clear adoption and the integration belongs in AGT long-term.
- Do not add obscure dependencies to core paths just to support a single external project.

## Decision Escalation

Ask a maintainer before proceeding with:

- new top-level packages or modules
- cross-cutting changes across 3+ packages
- security model changes
- public breaking API changes
- new framework integrations that materially expand the core surface
- CI/CD architecture changes

## Boundaries

- Never commit secrets, credentials, or real tokens.
- Never weaken security defaults, trust thresholds, or review requirements.
- Do not mix unrelated changes into docs-only or example-only PRs.
- Preserve honesty in docs: document shipped behavior, not aspirational behavior.

## Spam / SEO Outreach Filtering

Close or ignore PRs, issues, and discussions that are thinly disguised product placements or
SEO link-building attempts. Common patterns:

- Offers of "paid collaboration" to insert a product mention into docs, README, or blog posts
- PRs that add a product/service link to a resources or ecosystem list with no real integration
- Issues framed as feature requests that are actually product placements ("Add support for X")
- Generic flattery about the project followed by a pitch to include an unrelated tool
- No code contribution, no tests, no integration — just a link or brand mention

Action: close with a short note ("We don't accept sponsored content or paid placements") or
close without comment. Do not modify repo content to accommodate these requests.

## Version Bumps

When bumping the monorepo version (e.g. `3.2.0` → `3.2.1`):

- **DO** bump version strings in: `pyproject.toml`, `package.json`, `Cargo.toml`, `*.csproj`,
  `__init__.py`, and `README.md` banner.
- **DO NOT** bulk-replace version strings inside `package-lock.json` — transitive dependencies
  may share the same version number (e.g. `import-local@3.2.0`, `istanbul-reports@3.2.0`) and
  will get corrupted into non-existent versions. Instead, bump only `package.json`, then
  regenerate the lockfile with `npm install --legacy-peer-deps`.
- **DO NOT** bulk-replace inside `CHANGELOG.md` or `RELEASE_NOTES_*.md` — those are historical.
- After bumping, verify with: `Select-String -Path package-lock.json -Pattern '"<new-version>"'`
  and confirm only the SDK's own entries appear, not transitive deps.

## PR Hygiene

Before opening a PR:

- fix the PR title so it is semantic and consistently formatted
- ensure commits satisfy DCO/signoff requirements
- run the relevant docs link checks for changed docs
- treat expected 403-prone external links as markdown-link-check exceptions, not flaky failures
- fix spell-check issues on changed lines before requesting review

## Validation

- Run the narrowest existing tests for the paths you touched.
- For bug fixes, prefer a regression test that would fail without the change.
- For docs-only changes, make sure links, commands, and file paths are still correct.
- For SDK changes, verify language-specific build and test commands in the scoped instructions.

## PR Hygiene

- Before opening a PR, proactively check the expected repository gates instead of waiting for CI feedback.
- Use a semantic PR title in lowercase conventional-commit style such as `docs: ...`, `fix: ...`, or `feat: ...`.
- Ensure commits are DCO-compliant by including a signoff (`git commit -s`).
- For docs PRs, run `python scripts/docs/check_links.py` and `python scripts/docs/check_frontmatter.py` locally first.
- Avoid markdown links to external sites that return `403` to automated link checkers. When an external source must be cited but the host blocks bots, prefer plain-text or code-formatted URLs in docs and put clickable links in the PR description instead.