# harinee/agent-oss-guardrails architecture

> Architecture diagram of the GitHub repository harinee/agent-oss-guardrails, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harinee/agent-oss-guardrails
- Repository: https://github.com/harinee/agent-oss-guardrails

## Overview

This repository is a **content library for AI-agent guardrails**, not an application runtime. Its primary artifact is a set of reusable `*.skills.md` instruction blocks that teams can copy into agent setups to constrain dependency selection, tool usage, and supply-chain choices.

1. **Core purpose**
   The repo translates OSS/security governance into **modular agent instructions**. The “product” is the instruction set itself: baseline rules plus optional overlays that tailor behavior to a specific agent, ecosystem, or risk context.

2. **Primary content layer: foundational guardrails**
   `skills/foundational/` contains the two core policy starting points:
   - `oss-selection-baseline.skills.md`
   - `oss-selection-strict.skills.md`
   These are the base architecture layer for all other combinations.

3. **Policy overlays**
   `skills/overlays/` is the main composition mechanism. It splits guardrails into orthogonal dimensions:
   - **capabilities**: what the agent can do
   - **ecosystems**: the package/runtime ecosystem involved
   - **artifact-types**: the kind of dependency or tool being introduced
   - **contexts**: the risk environment or deployment setting
   This structure supports assembling only the constraints needed for a given scenario.

4. **Capability boundary**
   The `capabilities` overlays model the agent’s operational permissions, such as installing packages, opening PRs, running shell commands, or using tools/MCP. This is an important boundary because the repo assumes different guardrails are needed depending on what the agent can actually execute.

5. **Ecosystem-specific guidance**
   `skills/overlays/ecosystems/` contains language/package-manager-specific rules for:
   - container images
   - Java/Maven/Gradle
   - npm/Node
   - Python/pip
   This layer localizes dependency-selection behavior to the relevant ecosystem rather than applying generic advice everywhere.

6. **Artifact-type controls**
   `skills/overlays/artifact-types/` focuses on special classes of tools or dependencies, including:
   - CI/build tools and GitHub Actions
   - MCP servers/connectors
   - scanners and security tools
   These are treated separately because they can carry elevated trust or execution risk beyond ordinary libraries.

7. **Context/risk overlays**
   `skills/overlays/contexts/` captures environment sensitivity:
   - production
   - prototype/low-risk
   - regulated/sensitive
   This is the risk-adaptation layer, where the same base policy becomes stricter or more permissive depending on where it will be used.

8. **Pre-packaged combinations**
   `packaged/` contains ready-made composite skill sets such as:
   - `baseline-general.skills.md`
   - `strict-agent-high-autonomy.skills.md`
   - `npm-high-autonomy.skills.md`
   - `python-sensitive-repo.skills.md`
   These are curated bundles that reduce the need for manual composition across multiple overlay files.

9. **Examples as usage reference**
   `examples/` shows how the building blocks are intended to be combined for different agent profiles, such as generic, high-autonomy, and MCP-enabled agents. These examples are the closest thing to “integration tests” for the content architecture.

10. **Documentation as selection logic**
   The `docs/` folder explains the decision framework:
   - why the repo exists
   - how to choose a suitable skill set
   - design principles
   - mapping to standards
   - contribution rules
   This documentation is part of the control plane: it guides correct assembly of the instruction sets.

11. **How the pieces flow together**
   Typical usage is:
   foundational baseline → one or more overlays → optional packaged preset → consumed by an AI agent or team workflow.
   The repo does not enforce this at runtime; it provides the content structure and the decision guidance for assembling it correctly.

12. **Architectural boundary**
   There are no app servers, build pipelines, or external service integrations in this repo. The only “runtime” is the downstream AI agent that consumes these markdown skills. The repo’s boundary is therefore **instruction authoring and packaging**, not enforcement.

13. **Security/governance position**
   The README explicitly states this repo complements, but does not replace, SCA, SBOMs, code review, license review, vulnerability management, or incident response. That means the architecture is intentionally advisory: it shapes agent behavior, while formal security controls remain external.

14. **Repo shape summary**
   If you are drawing the architecture, model it as a **modular policy/content system** with four overlay dimensions, a foundational base, packaged presets, and documentation/examples around the edges. The key design feature is composability: one base policy can be specialized without duplicating the entire rule set.

Main entry points: [`skills/overlays/capabilities`](https://github.com/harinee/agent-oss-guardrails/tree/main/skills/overlays/capabilities) (Capabilities), [`docs/how-to-choose.md`](https://github.com/harinee/agent-oss-guardrails/blob/main/docs/how-to-choose.md) (How to choose), [`README.md`](https://github.com/harinee/agent-oss-guardrails/blob/main/README.md) (README), [`skills/foundational/oss-selection-baseline.skills.md`](https://github.com/harinee/agent-oss-guardrails/blob/main/skills/foundational/oss-selection-baseline.skills.md) (Baseline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Foundational policy"]
  node_baseline["Baseline<br/>foundational skill"]
  node_strict["Strict<br/>foundational skill"]
end

subgraph group_overlays["Overlay dimensions"]
  node_capabilities["Capabilities<br/>overlay family"]
  node_ecosystems["Ecosystems<br/>overlay family"]
  node_artifacts["Artifact types<br/>overlay family"]
  node_contexts["Contexts<br/>overlay family"]
  node_install["Install<br/>capability overlay"]
  node_tools["Tools/MCP<br/>capability overlay"]
  node_npm["npm/Node<br/>ecosystem overlay<br/>[npm-node.skills.md]"]
  node_python["Python/pip<br/>ecosystem overlay"]
  node_mcp["MCP servers<br/>artifact overlay"]
  node_production["Production<br/>context overlay"]
  node_prototype["Prototype<br/>context overlay"]
end

subgraph group_bundles["Packaged presets"]
  node_bundles["Bundles<br/>preset family"]
  node_baseline_general["Baseline general<br/>preset bundle"]
  node_strict_high["Strict high-autonomy<br/>preset bundle"]
  node_npm_high["npm high-autonomy<br/>preset bundle"]
  node_python_sensitive["Python sensitive<br/>preset bundle"]
end

subgraph group_reference["Usage reference"]
  node_generic_example["Generic example<br/>usage example"]
  node_high_autonomy_example["High autonomy<br/>usage example"]
  node_mcp_example["MCP enabled<br/>usage example"]
end

subgraph group_docs["Documentation"]
  node_readme["README<br/>overview doc<br/>[README.md]"]
  node_why["Why exists<br/>context doc<br/>[why-this-exists.md]"]
  node_choose["How to choose<br/>selection guide<br/>[how-to-choose.md]"]
  node_principles["Design principles<br/>policy design doc"]
  node_standards["Standards map<br/>mapping doc"]
  node_contrib["Contribution guide<br/>authoring guide"]
end

node_readme -->|"introduces"| node_baseline
node_readme -->|"frames"| node_capabilities
node_readme -->|"points to"| node_bundles
node_why -->|"supports"| node_readme
node_choose -->|"starts from"| node_baseline
node_choose -->|"adds"| node_capabilities
node_choose -->|"specializes by"| node_ecosystems
node_choose -->|"adds"| node_artifacts
node_choose -->|"adapts to"| node_contexts
node_principles -->|"guides"| node_baseline
node_principles -->|"guides"| node_strict
node_standards -->|"anchors"| node_readme
node_contrib -->|"extends"| node_capabilities
node_baseline -->|"variant"| node_strict
node_capabilities -->|"contains"| node_install
node_capabilities -->|"contains"| node_tools
node_ecosystems -->|"contains"| node_npm
node_ecosystems -->|"contains"| node_python
node_artifacts -->|"contains"| node_mcp
node_contexts -->|"contains"| node_production
node_contexts -->|"contains"| node_prototype
node_baseline -->|"composes into"| node_baseline_general
node_strict -->|"composes into"| node_strict_high
node_capabilities -->|"shapes"| node_strict_high
node_npm -->|"shapes"| node_npm_high
node_python -->|"shapes"| node_python_sensitive
node_prototype -->|"illustrates"| node_generic_example
node_tools -->|"illustrates"| node_mcp_example
node_mcp -->|"illustrates"| node_mcp_example
node_baseline_general -->|"mirrors"| node_generic_example
node_strict_high -->|"mirrors"| node_high_autonomy_example
node_npm_high -->|"mirrors"| node_high_autonomy_example

click node_readme "https://github.com/harinee/agent-oss-guardrails/blob/main/README.md"
click node_why "https://github.com/harinee/agent-oss-guardrails/blob/main/docs/why-this-exists.md"
click node_choose "https://github.com/harinee/agent-oss-guardrails/blob/main/docs/how-to-choose.md"
click node_principles "https://github.com/harinee/agent-oss-guardrails/blob/main/docs/design-principles.md"
click node_standards "https://github.com/harinee/agent-oss-guardrails/blob/main/docs/mapping-to-standards.md"
click node_contrib "https://github.com/harinee/agent-oss-guardrails/blob/main/docs/contribution-guide.md"
click node_baseline "https://github.com/harinee/agent-oss-guardrails/blob/main/skills/foundational/oss-selection-baseline.skills.md"
click node_strict "https://github.com/harinee/agent-oss-guardrails/blob/main/skills/foundational/oss-selection-strict.skills.md"
click node_capabilities "https://github.com/harinee/agent-oss-guardrails/tree/main/skills/overlays/capabilities"
click node_ecosystems "https://github.com/harinee/agent-oss-guardrails/tree/main/skills/overlays/ecosystems"
click node_artifacts "https://github.com/harinee/agent-oss-guardrails/tree/main/skills/overlays/artifact-types"
click node_contexts "https://github.com/harinee/agent-oss-guardrails/tree/main/skills/overlays/contexts"
click node_install "https://github.com/harinee/agent-oss-guardrails/blob/main/skills/overlays/capabilities/agent-can-install-packages.skills.md"
click node_tools "https://github.com/harinee/agent-oss-guardrails/blob/main/skills/overlays/capabilities/agent-can-use-tools-or-mcp.skills.md"
click node_npm "https://github.com/harinee/agent-oss-guardrails/blob/main/skills/overlays/ecosystems/npm-node.skills.md"
click node_python "https://github.com/harinee/agent-oss-guardrails/blob/main/skills/overlays/ecosystems/python-pip.skills.md"
click node_mcp "https://github.com/harinee/agent-oss-guardrails/blob/main/skills/overlays/artifact-types/mcp-servers-connectors.skills.md"
click node_production "https://github.com/harinee/agent-oss-guardrails/blob/main/skills/overlays/contexts/production.skills.md"
click node_prototype "https://github.com/harinee/agent-oss-guardrails/blob/main/skills/overlays/contexts/prototype-low-risk.skills.md"
click node_bundles "https://github.com/harinee/agent-oss-guardrails/tree/main/packaged"
click node_baseline_general "https://github.com/harinee/agent-oss-guardrails/blob/main/packaged/baseline-general.skills.md"
click node_strict_high "https://github.com/harinee/agent-oss-guardrails/blob/main/packaged/strict-agent-high-autonomy.skills.md"
click node_npm_high "https://github.com/harinee/agent-oss-guardrails/blob/main/packaged/npm-high-autonomy.skills.md"
click node_python_sensitive "https://github.com/harinee/agent-oss-guardrails/blob/main/packaged/python-sensitive-repo.skills.md"
click node_generic_example "https://github.com/harinee/agent-oss-guardrails/blob/main/examples/generic-agent.skills.md"
click node_high_autonomy_example "https://github.com/harinee/agent-oss-guardrails/blob/main/examples/high-autonomy-agent.skills.md"
click node_mcp_example "https://github.com/harinee/agent-oss-guardrails/blob/main/examples/mcp-enabled-agent.skills.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_baseline,node_strict toneBlue
class node_capabilities,node_ecosystems,node_artifacts,node_contexts,node_install,node_tools,node_npm,node_python,node_mcp,node_production,node_prototype toneAmber
class node_bundles,node_baseline_general,node_strict_high,node_npm_high,node_python_sensitive toneMint
class node_generic_example,node_high_autonomy_example,node_mcp_example toneRose
class node_readme,node_why,node_choose,node_principles,node_standards,node_contrib toneIndigo
```

## Components

### Foundational policy

Base guardrail instruction sets.

- [Baseline](https://github.com/harinee/agent-oss-guardrails/blob/main/skills/foundational/oss-selection-baseline.skills.md): foundational skill · Default OSS selection policy starting point. · `skills/foundational/oss-selection-baseline.skills.md`
- [Strict](https://github.com/harinee/agent-oss-guardrails/blob/main/skills/foundational/oss-selection-strict.skills.md): foundational skill · Tighter foundational policy for higher-risk use. · `skills/foundational/oss-selection-strict.skills.md`

### Overlay dimensions

Orthogonal policy modifiers for capabilities, ecosystems, artifact types, and risk context.

- [Capabilities](https://github.com/harinee/agent-oss-guardrails/tree/main/skills/overlays/capabilities): overlay family · Rules shaped by what the agent is allowed to do. · `skills/overlays/capabilities`
- [Ecosystems](https://github.com/harinee/agent-oss-guardrails/tree/main/skills/overlays/ecosystems): overlay family · Rules specialized by package or runtime ecosystem. · `skills/overlays/ecosystems`
- [Artifact types](https://github.com/harinee/agent-oss-guardrails/tree/main/skills/overlays/artifact-types): overlay family · Rules for elevated-risk dependency and tool classes. · `skills/overlays/artifact-types`
- [Contexts](https://github.com/harinee/agent-oss-guardrails/tree/main/skills/overlays/contexts): overlay family · Rules adjusted for environment sensitivity and risk. · `skills/overlays/contexts`
- [Install](https://github.com/harinee/agent-oss-guardrails/blob/main/skills/overlays/capabilities/agent-can-install-packages.skills.md): capability overlay · Agent may install packages. · `skills/overlays/capabilities/agent-can-install-packages.skills.md`
- [Tools/MCP](https://github.com/harinee/agent-oss-guardrails/blob/main/skills/overlays/capabilities/agent-can-use-tools-or-mcp.skills.md): capability overlay · Agent may use tools or MCP. · `skills/overlays/capabilities/agent-can-use-tools-or-mcp.skills.md`
- [npm/Node](https://github.com/harinee/agent-oss-guardrails/blob/main/skills/overlays/ecosystems/npm-node.skills.md): ecosystem overlay · Node and package-manager specific dependency guidance. · `skills/overlays/ecosystems/npm-node.skills.md`
- [Python/pip](https://github.com/harinee/agent-oss-guardrails/blob/main/skills/overlays/ecosystems/python-pip.skills.md): ecosystem overlay · Python dependency-selection guidance. · `skills/overlays/ecosystems/python-pip.skills.md`
- [MCP servers](https://github.com/harinee/agent-oss-guardrails/blob/main/skills/overlays/artifact-types/mcp-servers-connectors.skills.md): artifact overlay · Special handling for connectors and MCP servers. · `skills/overlays/artifact-types/mcp-servers-connectors.skills.md`
- [Production](https://github.com/harinee/agent-oss-guardrails/blob/main/skills/overlays/contexts/production.skills.md): context overlay · Stricter rules for production environments. · `skills/overlays/contexts/production.skills.md`
- [Prototype](https://github.com/harinee/agent-oss-guardrails/blob/main/skills/overlays/contexts/prototype-low-risk.skills.md): context overlay · Looser rules for low-risk or exploratory settings. · `skills/overlays/contexts/prototype-low-risk.skills.md`

### Packaged presets

Curated composite skill sets built from the base and overlays.

- [Bundles](https://github.com/harinee/agent-oss-guardrails/tree/main/packaged): preset family · Curated composite skill sets built from foundational policy and overlays. · `packaged`
- [Baseline general](https://github.com/harinee/agent-oss-guardrails/blob/main/packaged/baseline-general.skills.md): preset bundle · Common baseline composition for general use. · `packaged/baseline-general.skills.md`
- [Strict high-autonomy](https://github.com/harinee/agent-oss-guardrails/blob/main/packaged/strict-agent-high-autonomy.skills.md): preset bundle · Tighter preset for capable agents in higher-risk settings. · `packaged/strict-agent-high-autonomy.skills.md`
- [npm high-autonomy](https://github.com/harinee/agent-oss-guardrails/blob/main/packaged/npm-high-autonomy.skills.md): preset bundle · Preset tuned for Node/npm and high-autonomy agents. · `packaged/npm-high-autonomy.skills.md`
- [Python sensitive](https://github.com/harinee/agent-oss-guardrails/blob/main/packaged/python-sensitive-repo.skills.md): preset bundle · Preset for Python repos in sensitive contexts. · `packaged/python-sensitive-repo.skills.md`

### Usage reference

Example combinations showing intended assembly patterns.

- [Generic example](https://github.com/harinee/agent-oss-guardrails/blob/main/examples/generic-agent.skills.md): usage example · Reference composition for a general agent profile. · `examples/generic-agent.skills.md`
- [High autonomy](https://github.com/harinee/agent-oss-guardrails/blob/main/examples/high-autonomy-agent.skills.md): usage example · Reference composition for agents with broad execution rights. · `examples/high-autonomy-agent.skills.md`
- [MCP enabled](https://github.com/harinee/agent-oss-guardrails/blob/main/examples/mcp-enabled-agent.skills.md): usage example · Reference composition for agents that can use MCP tools. · `examples/mcp-enabled-agent.skills.md`

### Documentation

Decision logic and governance guidance for selecting skill sets.

- [README](https://github.com/harinee/agent-oss-guardrails/blob/main/README.md): overview doc · Repo purpose, boundary, and composition model. · `README.md`
- [Why exists](https://github.com/harinee/agent-oss-guardrails/blob/main/docs/why-this-exists.md): context doc · Explains the motivation and governance gap this repo addresses. · `docs/why-this-exists.md`
- [How to choose](https://github.com/harinee/agent-oss-guardrails/blob/main/docs/how-to-choose.md): selection guide · Decision framework for assembling the right skill set. · `docs/how-to-choose.md`
- [Design principles](https://github.com/harinee/agent-oss-guardrails/blob/main/docs/design-principles.md): policy design doc · Rules for composing and structuring guardrails. · `docs/design-principles.md`
- [Standards map](https://github.com/harinee/agent-oss-guardrails/blob/main/docs/mapping-to-standards.md): mapping doc · Relates the content to external governance and security standards. · `docs/mapping-to-standards.md`
- [Contribution guide](https://github.com/harinee/agent-oss-guardrails/blob/main/docs/contribution-guide.md): authoring guide · Rules for extending and maintaining the skill library. · `docs/contribution-guide.md`

## Connections

- README → Baseline: introduces · Explains the foundational starting point.
- README → Capabilities: frames · Describes the overlay dimensions.
- README → Bundles: points to · Shows curated composite presets.
- Why exists → README: supports · Provides motivation for the repository.
- How to choose → Baseline: starts from · Selection begins with a baseline policy.
- How to choose → Capabilities: adds · Selects capability-specific constraints.
- How to choose → Ecosystems: specializes by · Selects ecosystem-specific constraints.
- How to choose → Artifact types: adds · Selects special artifact controls.
- How to choose → Contexts: adapts to · Selects risk-context constraints.
- Design principles → Baseline: guides · Defines the composition model around the base policy.
- Design principles → Strict: guides · Explains when stricter posture applies.
- Standards map → README: anchors · Relates repo guidance to governance and standards.
- Contribution guide → Capabilities: extends · Shows how to author new overlays consistently.
- Baseline → Strict: variant · Represents a stricter foundational option.
- Capabilities → Install: contains · Capability-specific overlays.
- Capabilities → Tools/MCP: contains · Capability-specific overlays.
- Ecosystems → npm/Node: contains · Ecosystem-specific overlays.
- Ecosystems → Python/pip: contains · Ecosystem-specific overlays.
- Artifact types → MCP servers: contains · High-trust artifact overlays.
- Contexts → Production: contains · Risk-sensitive context overlays.
- Contexts → Prototype: contains · Lower-risk context overlays.
- Baseline → Baseline general: composes into · Base input for a common preset.
- Strict → Strict high-autonomy: composes into · Stricter base for a high-autonomy preset.
- Capabilities → Strict high-autonomy: shapes · Capability posture influences the preset.
- npm/Node → npm high-autonomy: shapes · Ecosystem-specific preset composition.
- Python/pip → Python sensitive: shapes · Ecosystem plus risk-context preset composition.
- Prototype → Generic example: illustrates · Example of low-risk or exploratory composition.
- Tools/MCP → MCP enabled: illustrates · Example requiring tool or MCP access.
- MCP servers → MCP enabled: illustrates · Example using MCP-related artifact guidance.
- Baseline general → Generic example: mirrors · Preset shown by example usage.
- Strict high-autonomy → High autonomy: mirrors · Preset shown by example usage.
- npm high-autonomy → High autonomy: mirrors · Node-focused preset shown in examples.
