# icherniukh/personify architecture

> Architecture diagram of the GitHub repository icherniukh/personify, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/icherniukh/personify
- Repository: https://github.com/icherniukh/personify

## Overview

1. **What this repo is**
   - Personify is a **persona-pack distribution system** for LLM agents: it defines a small, shared persona format and then exports that same content into several agent ecosystems.

2. **Canonical source of truth**
   - The main source lives in `src/`.
   - `src/assets/personalities/*.yaml` contains the persona packs themselves.
   - `src/skills/*/SKILL.md` contains the persona-related instruction assets for four capabilities:
     - `as-persona`
     - `extract-persona`
     - `list-personas`
     - `use-persona`

3. **Persona pack contract**
   - `docs/personality-pack-contract.md` is the schema/contract boundary for persona packs.
   - The same contract is mirrored in skill references under `*/references/personality-pack-contract.md`.
   - This contract is the key architectural boundary between “content authorship” and “platform packaging.”

4. **Core behavior model**
   - The repository is organized around two kinds of artifacts:
     - **Persona definitions**: YAML packs describing style/voice/reasoning traits.
     - **Activation instructions**: markdown skills/commands that tell an agent how to apply those packs.
   - The persona-selection and activation logic is not embedded in one runtime app; it is expressed as prompt assets plus packaging rules.

5. **Build and export layer**
   - `scripts/` contains the repository’s operational tooling.
   - `scripts/package.py` appears to be the main build orchestrator.
   - Export scripts convert the canonical source into platform-specific bundles:
     - `export_claude_plugin.py`
     - `export_claude_skills.py`
     - `export_gemini_extension.py`
   - Other helper scripts handle persona listing, selection, and token-overhead analysis.

6. **Platform adapters / distribution targets**
   - The repo ships separate output trees for different agent runtimes:
     - `claude/` for Claude Code plugins/skills
     - `codex/` for Codex commands and skills
     - `gemini/` for Gemini CLI extension assets
     - `opencode/` for OpenCode commands and skills
     - `pi/` for Pi package layout
   - These directories are effectively **platform-specific adapters** around the same source persona packs.

7. **Plugin and extension descriptors**
   - Top-level and per-target manifests wire the content into each ecosystem:
     - `.claude-plugin/`
     - `.codex-plugin/`
     - `gemini-extension.json`
     - platform-local `plugin.json`, `marketplace.json`, and command files
   - These descriptors are the integration points that make the packs discoverable and installable by each tool.

8. **Runtime flow for persona usage**
   - Typical usage flow is:
     1. List available personas.
     2. Select a persona for the current session.
     3. Apply a persona to a single task.
     4. Optionally extract a new persona from research.
   - In architectural terms, this is a **selection layer** over the persona asset library, not a separate service.

9. **Evaluation and regression testing**
   - `test/` contains a substantial test harness covering:
     - pack contract validation
     - persona selection and overlay behavior
     - extractor behavior
     - packaging/export correctness
     - token overhead calculations
     - style/behavior conformance for specific personas
     - activation benchmarks and some live-model tests
   - JSON fixtures such as `*_cases.json` and `live_cases.json` drive persona-specific regression coverage.

10. **Documentation as part of the system**
   - `docs/` is not just explanatory; it captures the design rules for:
     - persona injection
     - selection strategy
     - evaluation
     - token overhead
     - improvement backlog
   - This documentation defines how persona packs should be authored and assessed across platforms.

11. **Automation and release path**
   - `.github/workflows/build-artifacts.yml` indicates CI builds distributable artifacts from the canonical source.
   - The intended release path is: edit `src/` → run packaging scripts/tests → publish platform-specific outputs.

12. **Architectural boundary summary**
   - The repo’s main boundary is between **canonical persona content** and **exported agent-specific packaging**.
   - Everything else—commands, skills, plugins, extensions, and tests—exists to move that canonical content into different agent runtimes without changing the underlying persona contract.

Main entry points: [`scripts/export_claude_plugin.py`](https://github.com/icherniukh/personify/blob/main/scripts/export_claude_plugin.py) (Exporters), [`scripts/package.py`](https://github.com/icherniukh/personify/blob/main/scripts/package.py) (Packager), [`test`](https://github.com/icherniukh/personify/tree/main/test) (Tests), [`docs/personality-pack-contract.md`](https://github.com/icherniukh/personify/blob/main/docs/personality-pack-contract.md) (Pack contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Canonical source"]
  node_n1["Persona packs<br/>yaml assets"]
  node_n2["Source skills<br/>prompt assets"]
end

subgraph group_g2["Packaging tools"]
  node_n4["Packager<br/>build orchestrator<br/>[package.py]"]
  node_n5["Exporters<br/>export scripts"]
  node_n6["Persona tools<br/>utility scripts<br/>[persona_list.py]"]
end

subgraph group_g3["Platform adapters"]
  node_n7["Claude bundle<br/>platform output"]
  node_n8["Codex bundle<br/>platform output"]
  node_n9["Gemini bundle<br/>platform output"]
  node_n10["OpenCode bundle<br/>platform output"]
  node_n11["Pi bundle<br/>platform output"]
  node_n12["Claude plugin<br/>manifest<br/>[marketplace.json]"]
  node_n13["Codex plugin<br/>manifest<br/>[marketplace.json]"]
  node_n14["Gemini extension<br/>manifest"]
end

subgraph group_g4["Validation"]
  node_n15["Tests<br/>regression suite"]
  node_n16["Fixtures<br/>json cases<br/>[live_cases.json]"]
  node_n18["CI workflow<br/>automation"]
end

subgraph group_g5["Docs"]
  node_n3["Pack contract<br/>schema spec"]
  node_n17["Design docs<br/>guides"]
end

node_n1 -->|"package"| node_n4
node_n2 -->|"package"| node_n4
node_n3 -->|"constrains"| node_n1
node_n3 -->|"guides"| node_n2
node_n4 -->|"invoke"| node_n5
node_n4 -->|"uses"| node_n6
node_n5 -->|"emit"| node_n7
node_n5 -->|"emit"| node_n8
node_n5 -->|"emit"| node_n9
node_n5 -->|"emit"| node_n10
node_n5 -->|"emit"| node_n11
node_n7 -->|"described by"| node_n12
node_n8 -->|"described by"| node_n13
node_n9 -->|"described by"| node_n14
node_n15 -->|"validates"| node_n3
node_n15 -->|"checks"| node_n4
node_n15 -->|"checks"| node_n6
node_n15 -->|"driven by"| node_n16
node_n17 -->|"specifies"| node_n3
node_n18 -->|"runs"| node_n4
node_n18 -->|"runs"| node_n15

click node_n1 "https://github.com/icherniukh/personify/tree/main/src/assets/personalities"
click node_n2 "https://github.com/icherniukh/personify/tree/main/src/skills"
click node_n3 "https://github.com/icherniukh/personify/blob/main/docs/personality-pack-contract.md"
click node_n4 "https://github.com/icherniukh/personify/blob/main/scripts/package.py"
click node_n5 "https://github.com/icherniukh/personify/blob/main/scripts/export_claude_plugin.py"
click node_n6 "https://github.com/icherniukh/personify/blob/main/scripts/persona_list.py"
click node_n7 "https://github.com/icherniukh/personify/tree/main/claude"
click node_n8 "https://github.com/icherniukh/personify/tree/main/codex"
click node_n9 "https://github.com/icherniukh/personify/tree/main/gemini"
click node_n10 "https://github.com/icherniukh/personify/tree/main/opencode"
click node_n11 "https://github.com/icherniukh/personify/tree/main/pi"
click node_n12 "https://github.com/icherniukh/personify/blob/main/.claude-plugin/marketplace.json"
click node_n13 "https://github.com/icherniukh/personify/blob/main/.codex-plugin/marketplace.json"
click node_n14 "https://github.com/icherniukh/personify/blob/main/gemini-extension.json"
click node_n15 "https://github.com/icherniukh/personify/tree/main/test"
click node_n16 "https://github.com/icherniukh/personify/blob/main/test/live_cases.json"
click node_n17 "https://github.com/icherniukh/personify/tree/main/docs"
click node_n18 "https://github.com/icherniukh/personify/blob/main/.github/workflows/build-artifacts.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1,node_n2 toneBlue
class node_n4,node_n5,node_n6 toneAmber
class node_n7,node_n8,node_n9,node_n10,node_n11,node_n12,node_n13,node_n14 toneMint
class node_n15,node_n16,node_n18 toneRose
class node_n3,node_n17 toneIndigo
```

## Components

### Canonical source

Authoritative persona content and shared skill assets.

- [Persona packs](https://github.com/icherniukh/personify/tree/main/src/assets/personalities): yaml assets · Canonical personality definitions in shared pack format. · `src/assets/personalities`
- [Source skills](https://github.com/icherniukh/personify/tree/main/src/skills): prompt assets · Canonical persona activation and extraction instructions. · `src/skills`

### Packaging tools

Scripts that assemble and export persona assets.

- [Packager](https://github.com/icherniukh/personify/blob/main/scripts/package.py): build orchestrator · Main packaging entrypoint that coordinates exports. · `scripts/package.py`
- [Exporters](https://github.com/icherniukh/personify/blob/main/scripts/export_claude_plugin.py): export scripts · Platform-specific exporters for Claude, Gemini, and skills bundles. · `scripts/export_claude_plugin.py`
- [Persona tools](https://github.com/icherniukh/personify/blob/main/scripts/persona_list.py): utility scripts · Shared helpers for listing, selecting, and measuring persona overhead. · `scripts/persona_list.py`

### Platform adapters

Target-specific output trees and plugin descriptors.

- [Claude bundle](https://github.com/icherniukh/personify/tree/main/claude): platform output · Claude plugin and skills distribution tree. · `claude`
- [Codex bundle](https://github.com/icherniukh/personify/tree/main/codex): platform output · Codex commands and skills distribution tree. · `codex`
- [Gemini bundle](https://github.com/icherniukh/personify/tree/main/gemini): platform output · Gemini extension and skills distribution tree. · `gemini`
- [OpenCode bundle](https://github.com/icherniukh/personify/tree/main/opencode): platform output · OpenCode commands and skills distribution tree. · `opencode`
- [Pi bundle](https://github.com/icherniukh/personify/tree/main/pi): platform output · Pi package layout for persona skills and assets. · `pi`
- [Claude plugin](https://github.com/icherniukh/personify/blob/main/.claude-plugin/marketplace.json): manifest · Claude plugin descriptor and marketplace wiring. · `.claude-plugin/marketplace.json`
- [Codex plugin](https://github.com/icherniukh/personify/blob/main/.codex-plugin/marketplace.json): manifest · Codex plugin descriptor and marketplace wiring. · `.codex-plugin/marketplace.json`
- [Gemini extension](https://github.com/icherniukh/personify/blob/main/gemini-extension.json): manifest · Gemini extension descriptor for distribution. · `gemini-extension.json`

### Validation

Tests, fixtures, and benchmarks that protect contract and packaging behavior.

- [Tests](https://github.com/icherniukh/personify/tree/main/test): regression suite · Contract, packaging, behavior, extractor, and benchmark coverage. · `test`
- [Fixtures](https://github.com/icherniukh/personify/blob/main/test/live_cases.json): json cases · Persona-specific regression inputs and live-case scenarios. · `test/live_cases.json`
- [CI workflow](https://github.com/icherniukh/personify/blob/main/.github/workflows/build-artifacts.yml): automation · Builds distributable artifacts from the canonical source. · `.github/workflows/build-artifacts.yml`

### Docs

Design rules and contract boundaries for persona packs.

- [Pack contract](https://github.com/icherniukh/personify/blob/main/docs/personality-pack-contract.md): schema spec · Defines the persona-pack boundary and required structure. · `docs/personality-pack-contract.md`
- [Design docs](https://github.com/icherniukh/personify/tree/main/docs): guides · Selection, injection, evaluation, token overhead, and strategy notes. · `docs`

## Connections

- Persona packs → Packager: package · Canonical persona YAML is fed into the build orchestrator.
- Source skills → Packager: package · Canonical skills are assembled into platform bundles.
- Pack contract → Persona packs: constrains · The pack contract defines how persona YAML must be shaped.
- Pack contract → Source skills: guides · Activation instructions reference the same pack boundary.
- Packager → Exporters: invoke · Packaging dispatches platform exporters.
- Packager → Persona tools: uses · Build flow reuses shared persona utilities.
- Exporters → Claude bundle: emit · Exports Claude-specific bundles and plugin assets.
- Exporters → Codex bundle: emit · Exports Codex-specific bundles and commands.
- Exporters → Gemini bundle: emit · Exports Gemini-specific bundles and extension assets.
- Exporters → OpenCode bundle: emit · Exports OpenCode-specific bundles and commands.
- Exporters → Pi bundle: emit · Exports Pi-specific package layout.
- Claude bundle → Claude plugin: described by · Claude distribution is wired by its plugin manifest.
- Codex bundle → Codex plugin: described by · Codex distribution is wired by its plugin manifest.
- Gemini bundle → Gemini extension: described by · Gemini distribution is wired by its extension manifest.
- Tests → Pack contract: validates · Tests enforce the persona-pack contract boundary.
- Tests → Packager: checks · Tests cover packaging and export correctness.
- Tests → Persona tools: checks · Tests cover listing, selection, and token overhead utilities.
- Tests → Fixtures: driven by · Regression fixtures drive persona-specific test cases.
- Design docs → Pack contract: specifies · Documentation defines the authoritative pack contract and related rules.
- CI workflow → Packager: runs · CI triggers the packaging pipeline.
- CI workflow → Tests: runs · CI validates artifacts through the test suite.