defense-in-depth
AGENTS.md4 starsChanged 7 months agoMITView on GitHub
SYSTEM DIRECTIVE: This file is auto-loaded by all AI agents operating in this project. It is the ROOT of all governance. Read this FIRST. Executor: Gemini-CLI Project: defense-in-depth Type: Open Source NPM Package (MIT) Purpose: Git-based governance hooks for AI coding agents Parent: Extracted from an internal autonomous core system Runtime: TypeScript strict / Node.js ≥18 / CLI-first Status: Active Development (v0.6 — Federation Guards & Multi-Agent Governance) These are non-negotiable. No PR, no contributor, no agent may violate: [!CAUTION]…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository16 other files it gives its agents.
- .agents/AGENTS.mdAGENTS.md
- .agents/skills/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- skill-ai-dspy-validatorSkill
- Bootstrap AgentSkill
- CreatorSkill
- Deep ResearchSkill
- skill-devops-github-actionsSkill
- skill-guard-governanceSkill
- skill-impact-predictorSkill
- skill-review-codeSkill
- Self ReflectionSkill
- skill-surgical-refactorerSkill
- skill-test-architectSkill
- skill-threat-modeling-expertSkill
- [Skill Name]Skill
The file
We split this AGENTS.md into the rules it gives an agent
6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 25
NOT a full deployment (no lifecycle states, no PostgreSQL)
- Distinctive: line 26
NOT an AI agent or orchestrator
- Distinctive: line 27
NOT a replacement for CI/CD (complementary)
- Distinctive: line 28
NOT platform-specific (works with ANY AI agent, IDE, or workflow)
- Distinctive: line 186
No AI agent may modify these files without explicit human instruction:
- Distinctive: line 218
Contribution = Growth: Every merged PR makes this project (and the core system) smarter.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — Self-Awareness & Interoperability Index
SYSTEM DIRECTIVE: This file is auto-loaded by all AI agents operating in this project. It is the ROOT of all governance. Read this FIRST. Executor: Gemini-CLI
Layer 0 — Identity (WHO this project is)
Project: defense-in-depth Type: Open Source NPM Package (MIT) Purpose: Git-based governance hooks for AI coding agents Parent: Extracted from an internal autonomous core system Runtime: TypeScript strict / Node.js ≥18 / CLI-first Status: Active Development (v0.6 — Federation Guards & Multi-Agent Governance)
What This Project IS
- A lightweight governance middleware that runs as Git hooks
- A pluggable guard pipeline that validates code before it reaches Git history
- A cross-platform CLI tool (
npx defense-in-depth init/verify/doctor) - An extensibility framework via the
Guardinterface
What This Project is NOT
- NOT a full deployment (no lifecycle states, no PostgreSQL)
- NOT an AI agent or orchestrator
- NOT a replacement for CI/CD (complementary)
- NOT platform-specific (works with ANY AI agent, IDE, or workflow)
Layer 1 — Immutable Laws
These are non-negotiable. No PR, no contributor, no agent may violate:
- TypeScript Strict Only — No
any, nounknownescape, no.jsin core - Git-Only Enforcement — All validation happens through Git hooks. No runtime deps beyond Node
- Guards Must Be Pure — No side effects beyond reading files. No network calls. No state mutation
- Evidence Over Plausibility — Every claim must be verifiable. Tag:
[CODE],[RUNTIME],[INFER],[HYPO] - Zero Hollow Artifacts — No TODO/TBD/PLACEHOLDER in committed artifacts
- Conventional Commits — All commits follow
type(scope): description
Layer 2 — For AI Agents
[!CAUTION] IF YOU ARE AN AI AGENT: Do NOT read the full README. It is for humans. Load only what your current task requires:
| Mission | Load This |
| Understanding the codebase | src/core/types.ts → src/core/engine.ts |
| Adding a new guard | docs/dev-guide/writing-guards.md + .agents/contracts/guard-interface.md |
| Fixing a bug | src/core/engine.ts → relevant guard file |
| Configuration schema | docs/user-guide/configuration.md |
| CLI commands | docs/user-guide/cli-reference.md |
| Architecture deep-dive | docs/dev-guide/architecture.md |
| Agent Workspace Rules | docs/dev-guide/agent-workspace-guidelines.md |
| Rules & standards | .agents/rules/ directory |
| Strategic direction | STRATEGY.md |
| CI/CD | .github/workflows/ci.yml |
Agent Responsibilities
- Read
.agents/rules/before coding — consistency rules are absolute - Sign your work — append
Executor: <your-model-name>to artifacts - Never commit SSoT files — the
ssotPollutionguard will block you - Test first —
npm testmust pass before any PR
Layer 3 — Architecture Map
defense-in-depth/
├── src/
│ ├── core/ # Mandatory Pillars (engine, types, config)
│ │ ├── types.ts # Guard interface + future interfaces (v0.1–v0.8)
│ │ ├── engine.ts # Pipeline runner (sequential gate execution)
│ │ └── config-loader.ts # YAML config with deep merge defaults
│ ├── guards/ # Template Guards (pluggable validators)
│ │ ├── hollow-artifact.ts
│ │ ├── ssot-pollution.ts
│ │ ├── commit-format.ts
│ │ ├── branch-naming.ts
│ │ ├── phase-gate.ts
│ │ ├── federation.ts # v0.6 — Parent↔child governance
│ │ ├── ticket-identity.ts # v0.3 — TKID Lite
│ │ └── index.ts # Barrel export
│ ├── federation/ # v0.6 — Cross-project ticket providers
│ │ ├── file-provider.ts
│ │ ├── http-provider.ts
│ │ └── index.ts
│ ├── hooks/ # Git hook generators
│ │ ├── pre-commit.ts
│ │ └── pre-push.ts
│ └── cli/ # CLI commands
│ ├── index.ts # Entry point + router
│ ├── init.ts # Install hooks + config
│ ├── verify.ts # Run guards
│ └── doctor.ts # Health check
├── docs/ # 📖 Lazy-Load Documentation Hub
│ ├── user-guide/ # For users (config, CLI)
│ ├── dev-guide/ # For developers (architecture, guard authoring)
│ ├── quickstart.md # 60-second onboarding
│ └── vision/ # Meta architecture
│ ├── meta-architecture.md # Vision documents
│ └── system-blueprint.md # Unified connection mapping
├── templates/ # Shipped templates
├── .agents/ # Governance ecosystem
├── .github/ # CI + issue/PR templates
├── defense.config.yml # User config (created by init)
└── tests/ # Test suiteLayer 4 — Multi-Agent Operations (DiD Internal Strategy)
[!NOTE] This section describes how the defense-in-depth PROJECT ITSELF is developed. It is NOT a requirement for users of the defense-in-depth package. Users are free to adopt any workflow that suits their team. This is documented here for transparency and as a reference architecture.
Agent Taxonomy
defense-in-depth distinguishes between two classes of AI agents:
Operational Agents (Core — Human-Commanded)
These are the primary agents that build, design, and operate the system. They work in interactive sessions under direct human supervision.
| Agent | Role | Relationship | Config |
| Human | 👑 Sovereign | Commander, final authority | — |
| Main Agent (Gemini, Claude, etc.) | ⚙️ Architect & Executor | Directly commanded by Human | GEMINI.md / CLAUDE.md |
The Main Agent is the human's extended capability. It:
- Designs architecture, writes complex code, makes judgment calls
- Operates in real-time interactive sessions
- Has the human's trust and direct oversight
- Creates PRs that the human reviews and merges
External Agents (Third-Party — Leveraged Tools)
These are third-party services that the project leverages to optimize its development workflow. They operate autonomously within strict boundaries.
| Agent | Role | Nature | Config |
| Jules (Google) | 🏗️ Async Builder | Third-party SaaS, runs in Google Cloud VM | .agents/contracts/jules.md |
| CodeRabbit | 🔍 PR Reviewer | Third-party SaaS, auto-reviews PRs | .coderabbit.yaml |
External agents:
- Are NOT part of the core operational loop
- Operate asynchronously, without real-time human interaction
- Are constrained by configuration files, NOT by trust
- Can be added or removed without affecting the project's core workflow
Operational Flow
flowchart TD
H["👑 Human"] -->|"Direct command"| MA["⚙️ Main Agent<br/>(Operational)"]
H -->|"Delegates async task"| J["🏗️ Jules<br/>(External)"]
MA -->|"Creates PR"| GH["GitHub"]
J -->|"Creates PR"| GH
GH -->|"Auto-triggers"| CR["🔍 CodeRabbit<br/>(External)"]
CR -->|"Review feedback"| GH
GH -->|"Human reviews<br/>+ merges"| HEnvironment Setup (for Jules VM)
# Jules reads this to set up its isolated VM
npm ci
npm run build
npm testForbidden Zones (ALL non-human agents)
No AI agent may modify these files without explicit human instruction:
AGENTS.md,GEMINI.md,CLAUDE.md,STRATEGY.md.agents/**(governance rules, contracts, workflows).coderabbit.yaml.github/workflows/**- Root config files (
defense.config.yml,tsconfig.json,package.json)
Branch Convention
| Agent | Branch Pattern | Example |
| Jules (External) | feat/jules-*, fix/jules-* | fix/jules-http-timeout |
| Main Agent (Operational) | feat/*, fix/* | feat/federation-guard |
| Human | Any | hotfix/critical-bug |
[!CAUTION] No AI agent has merge authority. CodeRabbit can block (Request Changes) but CANNOT approve. Only the human maintainer merges. See
rule-hitl-enforcement.md.
Layer 5 — Growth & Federation
This project follows a federation model:
flowchart LR
CORE["🪐 Internal Core"] -->|"Push: proven guards,<br/>patterns, rules"| DID["🛡️ defense-in-depth (OSS)"]
DID -->|"Pull: community-contributed<br/>guards, improvements"| CORE
COMMUNITY["👥 Community"] -->|"PR: new guards,<br/>bug fixes, docs"| DIDContribution = Growth: Every merged PR makes this project (and the core system) smarter. Community-discovered patterns are harvested back into the parent system.
g8s Offer Gates (Wave-2 onboarded 2026-10-06)
This repository is onboarded to the g8s offer bundle (security profile):
- Registries:
.g8s/lane-bundles.yml(lane gates) +.g8s/trust-boundaries.yml(P0 paths) +.g8s/effort-classes.yml(effort defaults resolved byg8s submitfor dispatches scoped under this root — security-review→high, test→medium, docs→low). - Principle: gates are evidence, not ceremony — a FAIL is a catch (M2 metric), a pass is a claim with proof.
- Effort defaults are hypotheses until pass-rate telemetry earns them (g8s #550 rails); adjustments are operator-ratified diffs.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

