Coding agents

The single source of truth for humans and coding agents = AGENTS.md. It sits in the trishula repository. The agents: Copilot, Claude, Cursor, Hermes and others. Tool-specific files (CLAUDE.md, .github/copilot-instructions.md) point there; when anything disagrees, AGENTS.md wins.

Read it at the source. The GitHub-rendered page is always current. The file carries its own table of contents at its usual anchors:

• AGENTS.md — the guide: project map, testing standard, layer map, signing, the ADR process (docs/adr/), PR contract, labels, security rules.
• CONTRIBUTING.md — the working agreement (ground rules, PR template).

Architecture Decision Records

Structural changes carry an ADR in the same PR. Most slices are leaf-sized. The issue’s spec reference IS the design record; no ADR is needed. Write one only when the change introduces a new persistent artifact or removes or changes one. The artifacts: a wire format, a kernel map layout, a CRD field, a gate script.

The record home is docs/adr/ — the process and the record format.

Rules with teeth:

• Accepted ADRs are immutable. A change that contradicts an accepted ADR supersedes it with a new one. The accepted record is never rewritten.
• Never invent discussion, deciders or quotes. Cite commit/issue permalinks, or write “No substantive technical discussion recorded”.
• Bug fixes, docs, CI and dependency bumps don’t need ADRs.

This page intentionally does not mirror the file. A mirror drifts the moment the repo moves. The source-of-truth rule (AGENTS.md wins) already says where to look.