icherniukh/personify

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.