From 66b1771240f849874f2de0794008db50ec525f08 Mon Sep 17 00:00:00 2001 From: Bradley Gauthier <2234748+bradleygauthier@users.noreply.github.com> Date: Fri, 17 Apr 2026 09:10:55 -0500 Subject: [PATCH] docs: add AGENTS.md and agent discoverability layer AGENTS.md is the convergent standard agent context file (Linux Foundation AAIF stewardship, read natively by Codex, Cursor, Copilot, Aider). A concise file covering commands, the multi-language repo layout, style, crypto allowlist, boundaries, and the invariants that keep the protocol stable across languages (canonical JSON byte equality, conformance vectors, air-gap compatibility). README gains an AI Agents badge, a callout pointing at AGENTS.md, and a pre-Implementations "Explore the fit" H2 section with a sample prompt inviting a reader's agent to find places in their codebase that need tamper-evident audit coverage. --- AGENTS.md | 88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 17 +++++++++++ 2 files changed, 105 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..960602d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,88 @@ +# AGENTS.md: capsule + +Capsule Protocol Specification (CPS) plus reference implementations. Open source, Apache 2.0 with patent grant. **The spec in `spec/` is the source of truth, not any single implementation.** + +## Stack + +- **Spec:** `spec/` plus `conformance/` (16 valid + 15 negative golden vectors). Language-agnostic. +- **Python reference:** `reference/python/` publishes `qp-capsule` on PyPI. Python 3.11+, pynacl, hatchling. +- **TypeScript reference:** `reference/typescript/` publishes `@quantumpipes/capsule` on npm. TypeScript 5.9+ strict, Node 20.19+, ESM-only. +- **Ecosystem libraries** (not in this repo): capsule-go, capsule-litellm. + +## Commands + +Python (always `cd reference/python` first): +```bash +make install # pip install -e ".[storage,dev]" +make lint # ruff check src/ tests/ +make typecheck # mypy src/qp_capsule/ (strict) +make test # pytest, 100% coverage enforced (--cov-fail-under=100) +make test-golden # golden conformance vectors only +make test-all # lint + typecheck + test + golden +``` + +TypeScript (always `cd reference/typescript` first): +```bash +npm ci +npm run lint # tsc --noEmit +npm test # vitest run +npm run conformance # golden fixtures only +``` + +## Structure + +``` +spec/ CPS v1.0 specification, URI scheme, VERSION +conformance/ golden vectors every implementation must pass +reference/python/ qp-capsule (src/, tests/, Makefile, pyproject.toml) +reference/typescript/ @quantumpipes/capsule (src/, tests/, package.json) +docs/ architecture, security, 11 compliance mappings +examples/ language-agnostic example Capsules +nist-submission/ NIST materials +``` + +## Style + +- **No em dashes** anywhere in code, commits, or docs. Use commas, periods, colons, parentheses. +- Python: type hints on all public functions, async where I/O happens, mypy strict, filterwarnings = ["error"] (any new warning fails CI). +- TypeScript: strict mode, ESM-only (`.js` extensions in imports). +- **Crypto allowlist:** SHA3-256 (FIPS 202), Ed25519 (FIPS 186-5), ML-DSA-65 (FIPS 204), AES-256-GCM (FIPS 197). **Never** MD5, SHA1, SHA2, RSA, ECDSA-P256, 3DES, RC4. + +Canonical seal (Python): +```python +from qp_capsule import Capsule, Seal, CapsuleType, TriggerSection +c = Capsule(type=CapsuleType.AGENT, trigger=TriggerSection(source="bot", request="deploy")) +seal = Seal(); seal.seal(c); assert seal.verify(c) +``` + +## Git workflow + +- Conventional commits with scope: `feat(spec): ...`, `fix(python): ...`, `docs(compliance): ...`. +- **Never** include `Co-Authored-By`, `Generated by`, or any AI attribution. +- Protocol changes to `spec/` go through the CPS change proposal process (rare, requires spec-change issue plus updated golden vectors in the same PR). +- Implementation PRs must keep every golden vector green in every reference language. + +## Boundaries + +**Always:** +- Run `make test-all` (or `npm test`) in the affected reference before committing. +- Keep `canonicalize()` byte-identical across languages for the same input. +- Update `conformance/` vectors together with any spec change, same commit. + +**Ask first:** +- Any change to `spec/` (the protocol itself). +- Adding a dependency to a reference implementation. +- Adding a new reference language (open a new-implementation issue first). + +**Never:** +- Break the 16 golden vectors. Regenerate only via `make golden-regenerate` after an approved spec change. +- Introduce deprecated cryptography (see Style). +- Add runtime network dependencies. Air-gap compatibility is a protocol invariant. +- Change `to_dict()` or `canonicalize()` output in one implementation without matching changes in the others. + +## Related + +- Contributors: [CONTRIBUTING.md](./CONTRIBUTING.md) +- Security policy: [SECURITY.md](./SECURITY.md) +- Patent grant: [PATENTS.md](./PATENTS.md) +- Compliance mappings: [docs/compliance/](./docs/compliance/) diff --git a/README.md b/README.md index 086adfa..36de398 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,12 @@ Every AI action produces a Capsule — a tamper-evident, content-addressable rec [![Conformance](https://img.shields.io/badge/Conformance-16_vectors-ff69b4.svg)](./conformance/) [![FIPS](https://img.shields.io/badge/Crypto-FIPS_202%20·%20186--5%20·%20204-purple.svg)](#cryptographic-seal) [![Coverage](https://img.shields.io/badge/Coverage-100%25-brightgreen.svg)](./reference/python/) +[![AI Agents](https://img.shields.io/badge/AI%20Agents-AGENTS.md-blueviolet.svg)](./AGENTS.md) +> **AI coding agents:** start with [AGENTS.md](./AGENTS.md). It contains build and test commands, project structure, code style, crypto allowlist, and the guardrails that keep the protocol intact. + --- ## The Protocol @@ -188,6 +191,20 @@ See more examples in [`examples/`](./examples/). --- +## Explore the fit with your AI coding agent + +Paste this prompt into Claude Code, Cursor, Codex, or any other agent: + +```text +Read the Capsule Protocol README and AGENTS.md at https://github.com/quantumpipes/capsule. +Then survey my codebase for every place an AI agent takes autonomous action (tool calls, +LLM completions, scheduled jobs, deploy triggers) and currently lacks a tamper-evident +audit trail. For each, explain what a capsule would record. Recommend the single +highest-leverage place to start, with concrete files and functions to change. +``` + +--- + ## Implementations ### Reference Implementations