ai: add AI guidance, personas

Introduce a structured AI assistance framework for the project:

- AGENTS.md: single, comprehensive AI guidance file for all tools
  (Claude Code, Codex, Copilot, Cursor). Covers the privilege-separation
  architecture invariant, build/test instructions, code style (including
  a rule against deep preprocessor conditionals), memory allocator policy,
  IPC modification procedure, module-specific doc pointers, and a
  contribution checklist split into agent-runnable and human-judgment items.
  Includes a security disclosure gate that redirects potential vulnerability
  reports to the confidential issue tracker before any public MR is opened.

- contrib/ai/personas/ocserv-core-dev.md: maintainer-facing persona with
  project-specific protocols for anti-hallucination (GnuTLS/protobuf/seccomp
  APIs), memory safety (talloc-first, gnutls_malloc exception), a taxonomy
  of ocserv-specific vulnerability classes, and a self-verification protocol
  that distinguishes what an agent can check automatically from what requires
  human judgment.

- contrib/ai/personas/ocserv-contributor.md: external-contributor-facing
  persona with mandatory architecture orientation, a prominent security
  disclosure gate, five hard guardrails (privilege boundary, syscall
  portability, GnuTLS-only, protobuf regeneration, talloc), and a
  step-by-step workflow for features, bug fixes, and security fixes.

Signed-off-by: Nikos Mavrogiannopoulos <n.mavrogiannopoulos@gmail.com>
This commit is contained in:
Nikos Mavrogiannopoulos
2026-04-25 12:08:32 +02:00
parent a65f2c22a2
commit 855966cd95
5 changed files with 1154 additions and 0 deletions
+21
View File
@@ -0,0 +1,21 @@
# AI Assistance Framework
This directory contains persona files for use with AI coding agents working on ocserv.
See [`AGENTS.md`](../../AGENTS.md) in the repository root for the full agent guide.
## Personas
| File | Intended for |
|------|-------------|
| `personas/ocserv-core-dev.md` | Maintainers: bug investigation, code review, design, release |
| `personas/ocserv-contributor.md` | External contributors: features, bug fixes, security fixes |
Load the appropriate file as a system prompt prefix in your AI tool before starting work.
## Acknowledgment
The structure of this framework — composable persona and protocol files that can be
combined into reliable, repeatable AI prompts — is inspired by
[PromptKit](https://github.com/microsoft/PromptKit) by Microsoft. The protocol names
(anti-hallucination, memory-safety, security-vulnerability, self-verification) follow
PromptKit's vocabulary. All content is written specifically for ocserv and its codebase.