Tech Persona Card V1.0

# Tech Persona Card Specification v1.0

> ⚠️ **Deprecated (2026-07-06).** Frozen for external link stability — do not implement
> against this spec. The `identity`/`behavior`/`style` file-pointer model and the
> `capabilities`/`scenarios` fields this spec defines turned out to let judgment content
> (authorization tiers, verification-skip instructions, priority orderings) accrete into
> what was supposed to be a voice-only layer, with no gate that ever checked for it — see
> `docs/specs/persona-voice-card-v1.0.md` for the replacement lineage (new name, not "v2",
> so no reader assumes the old capability fields still parse). `docs/specs/persona-card.schema.json`
> is likewise frozen. Existing personas have been migrated to `config/personas/<slug>.json`
> per the new spec; nothing in this repo validates against this document anymore.

> A portable, structured format for defining AI agent personalities in technical workflows.

**Status:** Draft (frozen/deprecated — see banner above)  
**Authors:** telagod  
**Created:** 2026-05-16  
**License:** CC-BY-4.0  

---

## 1. Introduction

### 1.1 Problem Statement

Every AI agent platform (Claude Code, Codex CLI, Gemini CLI, Microsoft Copilot, OpenClaw) handles agent persona the same way: dump everything into a single freeform text field (`instructions`, `system_prompt`, `CLAUDE.md`). This creates four problems:

1. **No portability** — a persona written for Claude cannot be used in Codex without rewriting
2. **No composability** — identity, behavior rules, and output style are tangled in one blob
3. **No marketplace** — without a structured format, persona sharing is copy-paste at best
4. **No validation** — cross-combining personas with styles can produce conflicting instructions (e.g., two different self-references in the same prompt)

### 1.2 Scope

This specification defines a **Tech Persona Card** — a JSON document describing an AI agent's identity, behavioral rules, and output preferences for technical work (software engineering, security, DevOps, architecture, data science, etc.).

It is NOT:
- A replacement for skill definitions (see [agentskills.io](https://agentskills.io/specification))
- A general-purpose character card (see [Character Card V2](https://github.com/malfoyslastname/character-card-spec-v2))
- An authentication/authorization protocol (see [W3C DID](https://www.w3.org/TR/did-core/), [IETF Txn-Tokens](https://datatracker.ietf.org/doc/draft-ietf-oauth-transaction-tokens/))

### 1.3 Design Principles

1. **Structured over freeform** — machine-readable fields where possible, freeform text only where structure would destroy expressiveness
2. **Composable** — identity, behavior, and style are separate layers that can be mixed and matched
3. **Portable** — one card works across Claude, Codex, Gemini, Copilot, and any future agent
4. **Backward-compatible** — can degrade gracefully to a single system prompt string for platforms that only support freeform text
5. **Extensible** — unknown fields MUST be preserved, not rejected

### 1.4 Keyword Semantics

The keywords "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" follow [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).

---

## 2. Format

A Tech Persona Card is a JSON document. The file SHOULD be named `persona-card.json` and placed at the root of a persona package directory.

### 2.1 Directory Structure