Agent Covenant

Centralized development rules for AI coding agents (GitHub Copilot, Cursor, Claude Code, Codex CLI, Gemini CLI, Antigravity, OpenCode).

AI agents: see AGENTS.md for project-specific instructions (where to create content, validation commands, schema formats).

Table of Contents

• Architecture
• Quick Start
• Requirements
• Content Organization
• Docs
• Supported Agents
• Usage
• Hooks
• MCP Servers
• Subagents
• LSP (Code Intelligence)
• Scripts
• Development
• Quarterly Review
• License

Architecture

Hybrid rules architecture — two complementary layers:

Layer	What	When loaded	Purpose
Kernel (F1)	rules/agents/*-global.md	Always, every turn	Ultra-compressed identity + per-section skill pointers
Skills (F2)	skills/<name>/SKILL.md	On-demand, agent-detected	Full detail for the relevant domain

The kernel stays under 6,000 chars. Skills provide depth without bloating the always-on context.

Core rule skills (6 pillars): engineering-standards · operating-protocol · context-management · tool-usage · token-efficiency · governance

Quick Start

make check       # Full pipeline: lint → fmt-check → validate → test
make sync        # Deploy to all enabled agents
make sync-dry    # Preview without writing
make list        # List available agents

Requirements

brew install yq shellcheck shfmt bats-core node uv docker

Content Organization

agent-covenant/
├── manifest.example.yaml      # Source of truth template (copy to manifest.yaml for local config)
├── content/
│   ├── rules/                 # Agent behavior rules (kernel + core) → README
│   ├── skills/                # 60 active skills (on-demand, progressive disclosure, schema v2) → README
│   ├── workflows/             # 11 slash-command workflows → README
│   ├── prompts/               # 0 reusable prompts → README
│   ├── subagents/             # 15 active sub-agents + README → README
│   ├── hooks/                 # Deterministic lifecycle hooks (7 agents) → README
│   └── mcp/                   # MCP server configuration (16 servers) + agent config → README
├── docs/                      # Architecture documentation → below
├── scripts/                   # Sync, validate, quarterly review
├── tests/                     # Bats test suite
├── Makefile                   # lint, fmt, test, validate, sync targets
└── mcps/                      # Custom MCP server source

Each content/ subdirectory has its own README.md with purpose, format, and links to deep-dive docs.

Docs

Directory	Contents
docs/adr/	24 Architecture Decision Records (0001–0024)
docs/architecture/	Architecture diagram
docs/grafana/	Importable skill usage dashboard (JSON)
docs/plans/	Active revision plans: refactor-05-aug-2026.md (fintech-bias removal)
docs/reference/	Detailed catalogs: skills, MCP, subagents, workflows, rules, LSP, issue-as-prompt, subagent-strategy-mapping
docs/SKILL_QUALITY_STANDARD.md	7-pillar quality standard for skills (scoring, examples, CI)
docs/reports/	Repository reports and audits
docs/validation/	Canonical paths, skill invocation matrix

Template location rule: all templates required by content/ live under content/skills/_TEMPLATE/ (not docs/). See AGENTS.md §Validation Rules → Skills.

Supported Agents

Agent	Status	Skills	Subagents	MCP	Hooks	Workflows	Prompts
claude-desktop	Enabled	—	—	Yes	—	—	—
claude-code	Enabled	Yes	Yes	Yes	Yes	Yes	—
copilot-cli	Enabled	Yes	—	—	—	—	—
antigravity	Enabled	Yes	—	Yes	—	Yes	—
opencode	Enabled	Yes	Yes	Yes	Yes	—	—

Usage

make sync              # Sync to all enabled agents
make sync-dry          # Dry run
make sync-force        # Force redeploy (bypass cache)

# Single agent
./scripts/sync.sh --agent windsurf
./scripts/sync.sh --agent claude-code

# Extra flags
./scripts/sync.sh --backup --debug

make validate                      # Check manifest, files, and frontmatter
make validate-mcp-config           # MCP portability: bare binaries, no PATH env, no secrets
make validate-skill-refs           # Skill coherence check (non-blocking)
make validate-canonical-paths      # Canonical path audit (non-blocking)
make test                          # Run bats tests

Hooks

Deterministic shell hooks triggered by agent lifecycle events (SessionStart, PreToolUse, PostToolUse, Stop). 7 agents configured, 7 hooks for Claude Code. Enforce behavior the model might forget.

→ Full hook catalog: content/hooks/README.md
→ Coverage map: docs/adr/0004-hook-coverage-map.md

MCP Servers

16 MCP servers configured in content/mcp/mcp.json — GitHub, Grafana, Atlassian, AWS, Notion, and more. Synced automatically per agent.

→ Server catalog: content/mcp/README.md
→ Token configuration: docs/reference/mcp-servers.md

Subagents

15 active AI sub-agents — organized as read-only analysis (6), review specialists (6), and write agents (3).

→ Full catalog: content/subagents/README.md · docs/reference/subagent-schema.md

LSP (Code Intelligence)

11 LSP servers mapped to supported tech stacks. OpenCode: native auto_lsp. Claude Code: plugin-based.

./scripts/setup-lsp.sh            # Install + verify
./scripts/setup-lsp.sh --check-only

→ Full mapping: docs/reference/lsp-reference.md

Scripts

Script	Purpose
sync.sh	Reads manifest.yaml, deploys rules/skills/workflows/subagents/MCP/hooks to agents
validate.sh	Manifest syntax, file references, frontmatter consistency
validate-skill-references.sh	Skill cross-reference check (non-blocking)
validate-canonical-paths.sh	Canonical path audit (non-blocking)
validate-skill-quality.py	Score all skills against 7-pillar standard (CI-blocking)
quarterly_review.py	Staleness, schema v2 scan, category distribution
setup-lsp.sh	Bootstrap LSP plugins + binary verification
seed-memory.sh	Pre-seed MCP memory with core directives

Development

Code Style

Rule	Value
Shell indent	4 spaces
Shell header	set -euo pipefail
Formatter	shfmt -i 4 -ci
Linter	shellcheck -x
Test framework	bats-core

Commit Messages

Follow Conventional Commits:

feat(rules): add rust best practices
fix(sync): handle empty glob paths
docs(readme): update agent table

Quarterly Review

python3 scripts/quarterly_review.py --stale-days 90 --output docs/review-$(date +%Y-%m).md

Outputs: staleness report, schema issues, category distribution, quality opportunities.

License

MIT