AGENTS.md — claude-foundation

A Claude Code plugin, not a package in the import graph. It also holds the repo's only CLAUDE.md.

This directory packages the foundation plugin: reusable skills, least-privilege subagents and lifecycle hook guards, plus the foundation_tools validators that gate them. It is staged in-tree pending extraction, so it behaves like its own repository while living inside this one.

Map

Diagram

flowchart TD
  accTitle: claude-foundation plugin surface and hook fail modes
  accDescr: The plugin manifest publishes skills, subagents and hooks; the pre-tool guard fails closed and denies on any error while the post-edit verifier and session logger always exit zero, and the foundation tools validators gate the whole surface against a committed baseline.

  MAN[".claude-plugin/<br/>plugin + marketplace"]
  SK["skills/<br/>foundation:* skills"]
  AG["agents/<br/>4 subagents"]
  HK["hooks/hooks.json"]
  GUARD["pre_tool_guard.py<br/>FAILS CLOSED"]
  ADV["post_edit_verify.py<br/>session_logger.py<br/>FAIL OPEN"]
  ENV["CLAUDE_FOUNDATION_*<br/>env config only"]
  TOOLS["foundation_tools/<br/>validate, scan, compat"]
  BASE["tests/<br/>backwards_compat_baseline.json"]

  MAN --> SK
  MAN --> AG
  MAN --> HK
  HK --> GUARD
  HK --> ADV
  ENV --> GUARD
  ENV --> ADV
  SK --> TOOLS
  AG --> TOOLS
  HK --> TOOLS
  TOOLS --> BASE

  classDef here fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px
  class MAN here

Rules that bite here

• This directory holds the repo's only CLAUDE.md, and it decides what you can see. Under Claude Code's default project-instructions setting, a CLAUDE.md in the working directory or above it makes Claude read CLAUDE.md files only, so an agent working here would otherwise receive none of the repo-wide contract. The single line @AGENTS.md at the top of CLAUDE.md is what pulls this file — and through it ../AGENTS.md — back into context. Delete that line and every agent working here goes blind, silently.
• The hook fail modes are asymmetric on purpose (ADR 0002). pre_tool_guard.py fails CLOSED — a matched deny rule and any internal error both deny, so a crash can never let a tool call through. post_edit_verify.py and session_logger.py fail OPEN and always exit 0, so a broken config cannot paralyse every edit in a consumer repo. Never invert either one.
• Component names are append-only within a major version. Removing or renaming a skill, subagent or hook needs a major bump, then python -m foundation_tools.backwards_compat --root . --update in the same change — run after the bump, since it snapshots the current one.
• No literals in hook behaviour. Everything configurable comes from a CLAUDE_FOUNDATION_* environment variable, and foundation_tools.scan enforces that against an allowlist policy.
• Staged in-tree, and still inside this repo's gates. Run its own commands from here as if this were the repository root, but tests/** is a protected path and its 85 floor is declared in both pyproject.toml and scripts/quality-gate.sh.

Verify

make -C claude-foundation check

Subagents

See also