CLAUDE.md

@AGENTS.md

The import above is load-bearing, not decoration. This is the repo's only CLAUDE.md, and 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 inside claude-foundation/ would otherwise receive none of the repo's AGENTS.md orientation. The import pulls the sibling claude-foundation/AGENTS.md back in, which in turn points at the root. Do not delete it without moving this file's content up.

Build/Test Commands

pytest                                # unit tests (hooks, validator, eval gate)
ruff check .                          # lint
ruff format --check .                 # formatting
mypy tools                            # strict type checking
python -m foundation_tools.validate   # frontmatter + manifest schema validation
python -m foundation_tools.scan       # no-hardcode scanner (allowlist policy)
python -m foundation_tools.backwards_compat  # append-only component-name gate
claude plugin validate .              # official plugin structure checker
bash tests/smoke/install_smoke.sh     # install smoke test (--plugin-dir fast path)

Release gate (run on-demand before tagging, not on a schedule): python -m foundation_tools.eval_gate plus python -m foundation_tools.backwards_compat (ADR 0004). Behavioral evals never gate merges.

After applying a skill/agent/hook removal or rename and bumping the major version, run python -m foundation_tools.backwards_compat --root . --update and commit the resulting tests/backwards_compat_baseline.json diff in the same PR as the bump — --update snapshots the live tree and its current major version, so running it before the removal/bump would freeze the old surface under the old major instead of the new one. The gate warns if the baseline is stale relative to the current major, but does not block on it.

Architecture Decisions

• ADR 0001: packaged as a plugin plus self-hosted marketplace, not a copy-template; consumers pin semver tags via marketplace ref/sha.
• ADR 0002: pre-tool-guard fails closed (exit 2 / permissionDecision: "deny"); post-edit-verify and session-logger fail open (always exit 0).
• ADR 0003: skill-creator evals gated by the thin foundation_tools.eval_gate wrapper (release-blocking only); stdlib-logging JSONL instead of structlog so hooks run dependency-free.
• ADR 0004: implements ADR 0001 pt. 4's append-only contract via foundation_tools.backwards_compat, diffing a checked-in tests/backwards_compat_baseline.json against the live skill/agent/hook surface; removals without a major version bump fail the release gate, additions never do.

Compatibility Contract

• Component names (skills, subagents, hooks) are append-only within a major version; renames/removals require a major bump and a manifest-diff check enforces this at release time.
• The plugin name foundation owns the foundation:* namespace; the repository name (claude-foundation) is only the marketplace name.

Known Limitations

• Behavioral skill evals are non-deterministic and require Anthropic API access and credits; they run only in the on-demand release gate above, never per-PR and never on a schedule (no nightly run exists — see the 2026-08-17 peer review note in ADR 0034 in the parent Agents repo if a real nightly run is ever added).
• Hooks assume a POSIX environment, or Windows with Python 3.11+ on PATH; hook scripts are stdlib-only by design (ADR 0003).

Recommended Per-File Verification

Set CLAUDE_FOUNDATION_VERIFY_CMD to enable automatic lint/formatting feedback after every edit:

export CLAUDE_FOUNDATION_VERIFY_CMD="python -m ruff check {file}"

This activates the existing post_edit_verify.py hook (ADR 0022 §4). The hook is advisory (fail-open, always exit 0) — findings appear as model context, never blocking edits. On Windows, use python -m ruff check {file} (not a .sh script) for cross-platform compatibility.