From ddf7d2b2fffb38228c68cacebbbda58e8d633b8d Mon Sep 17 00:00:00 2001 From: salvacybersec Date: Sun, 22 Mar 2026 10:41:05 +0300 Subject: [PATCH] docs: comprehensive README rewrite with architecture diagrams - ASCII persona tree, architecture diagram, escalation flow - Complete variant table for all 29 personas (108 variants) - Config-driven build system documentation - Integration examples (Python, CLI, multi-persona switching) - New user onboarding guide - Updated stats to reflect current state Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 367 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 230 insertions(+), 137 deletions(-) diff --git a/README.md b/README.md index b27e4db..43ca43b 100644 --- a/README.md +++ b/README.md @@ -1,102 +1,157 @@ # Persona Library -Platform-agnostic LLM persona library for AI agents. 29 personas across 10 domains with 25+ specialization variants. +> Platform-agnostic system prompt library for LLM agents. +> 29 personas. 10 domains. 108 variants. 20,000+ lines of production-grade prompts. + +``` + ┌─ Neo ─── Phantom ─── Cipher ─── Specter ─── Bastion ─── Vortex ─── Sentinel + │ CYBER WEB CRYPTO MALWARE DFIR NETWORK CTI + │ + ├─ Frodo ─── Oracle ─── Ghost ─── Wraith ─── Echo + │ STRATEGIC OSINT PSYOP HUMINT SIGINT + │ + ├─ Marshal ─── Warden ─── Centurion ─── Corsair +PERSONAS ─┤ DOCTRINE WEAPONS MIL-HISTORY SPEC-OPS + │ + ├─ Arbiter ─── Ledger ─── Tribune + │ INT'L LAW FININT POLITICS + │ + ├─ Chronos ─── Scribe ─── Polyglot ─── Herald + │ HISTORY FOIA LINGINT MEDIA + │ + └─ Architect ── Forge ── Scholar ── Sage ── Medic ── Gambit + DEVOPS DEV ACADEMIA PHILOSOPHY CBRN CHESS +``` ## Quick Start ```bash -# Generate all formats (.yaml, .json, .prompt.md) +# 1. Clone +git clone https://gitea.taygun.net.tr/salvacybersec/personas.git +cd personas + +# 2. Configure (optional — works without config too) +cp config.example.yaml config.yaml +# Edit config.yaml with your tools, data sources, infrastructure + +# 3. Build +pip install pyyaml python3 build.py -# Use a persona as system prompt -cat .generated/neo/general.prompt.md - -# Use structured data for API integration -cat .generated/frodo/iran.json +# 4. Use +cat generated/neo/general.prompt.md # raw system prompt +cat generated/frodo/iran.json # structured JSON +cat generated/sentinel/apt-profiling.yaml # YAML with metadata ``` -## Domains & Personas +## Personas & Variants + +### Cybersecurity (7 personas, 25 variants) -### Cybersecurity (7) | Codename | Role | Hitap | Variants | |----------|------|-------|----------| -| **Neo** | Red Team Lead / Exploit Dev | Sıfırıncı Gün | general, redteam, exploit-dev, wireless | -| **Phantom** | Web App Security / Bug Bounty | Beyaz Şapka | general, api-security | +| **Neo** | Red Team Lead / Exploit Dev | Sıfırıncı Gün | general, redteam, exploit-dev, wireless, social-engineering, mobile-security, salva | +| **Phantom** | Web App Security / Bug Bounty | Beyaz Şapka | general, api-security, bug-bounty | | **Cipher** | Cryptography & Crypto Analysis | Kriptoğraf | general | -| **Specter** | Malware Analyst / Reverse Engineer | Cerrah | general | -| **Bastion** | Blue Team / DFIR | Muhafız | general, forensics, threat-hunting | +| **Specter** | Malware Analyst / Reverse Engineer | Cerrah | general, firmware | +| **Bastion** | Blue Team / DFIR | Muhafız | general, forensics, threat-hunting, incident-commander | | **Vortex** | Network Ops / Traffic Analysis | Telsizci | general, cloud-ad | -| **Sentinel** | CTI / Threat Intelligence | İzci | general, apt-profiling, mitre-attack | +| **Sentinel** | CTI / Threat Intelligence | İzci | general, apt-profiling, mitre-attack, darknet | + +### Intelligence (5 personas, 27 variants) -### Intelligence (5) | Codename | Role | Hitap | Variants | |----------|------|-------|----------| -| **Frodo** | Strategic Intelligence Analyst | Müsteşar | general, middle-east, russia, iran, africa, china | -| **Oracle** | OSINT & Digital Intelligence | Kaşif | general | -| **Ghost** | PSYOP & Information Warfare | Propagandist | general, cognitive-warfare | -| **Wraith** | HUMINT & Counter-Intelligence | Mahrem | general, source-validation | -| **Echo** | SIGINT / COMINT / ELINT | Kulakçı | general, nsa-sigint | +| **Frodo** | Strategic Intelligence Analyst | Müsteşar | general, middle-east, russia, iran, africa, china, pakistan, india, nato-alliance, nuclear, energy-geopolitics, turkey, salva | +| **Oracle** | OSINT & Digital Intelligence | Kaşif | general, crypto-osint, salva | +| **Ghost** | PSYOP & Information Warfare | Propagandist | general, cognitive-warfare, russian-info-war, salva | +| **Wraith** | HUMINT & Counter-Intelligence | Mahrem | general, source-validation, case-studies, salva | +| **Echo** | SIGINT / COMINT / ELINT | Kulakçı | general, nsa-sigint, electronic-order-of-battle, salva | + +### Military & Strategy (4 personas, 24 variants) -### Military & Strategy (4) | Codename | Role | Hitap | Variants | |----------|------|-------|----------| -| **Marshal** | Military Doctrine & Strategy | Mareşal | general, nato-doctrine, hybrid-warfare | -| **Warden** | Defense Analyst / Weapons Systems | Topçubaşı | general | -| **Centurion** | Military History & War Analysis | Vakanüvis | general | -| **Corsair** | Special Operations & Irregular Warfare | Akıncı | general | +| **Marshal** | Military Doctrine & Strategy | Mareşal | general, nato-doctrine, hybrid-warfare, russian-doctrine, chinese-doctrine, turkish-doctrine, iranian-military, wargaming, salva | +| **Warden** | Defense Analyst / Weapons Systems | Topçubaşı | general, drone-warfare, naval-warfare, electronic-warfare, salva | +| **Centurion** | Military History & War Analysis | Vakanüvis | general, ukraine-russia, ottoman-wars, salva | +| **Corsair** | Special Operations & Irregular Warfare | Akıncı | general, proxy-warfare, salva | + +### Law, Economics & Politics (3 personas, 9 variants) -### Law, Economics & Politics (3) | Codename | Role | Hitap | Variants | |----------|------|-------|----------| -| **Arbiter** | International Law & War Crimes | Kadı | general, sanctions | -| **Ledger** | Economic Intelligence / FININT | Defterdar | general, sanctions-evasion | -| **Tribune** | Political Science & Regime Analysis | Müderris | general | +| **Arbiter** | International Law & War Crimes | Kadı | general, sanctions, salva | +| **Ledger** | Economic Intelligence / FININT | Defterdar | general, sanctions-evasion, salva | +| **Tribune** | Political Science & Regime Analysis | Müderris | general, salva | + +### History & Archives (2 personas, 6 variants) -### History & Archives (2) | Codename | Role | Hitap | Variants | |----------|------|-------|----------| -| **Chronos** | World History & Civilization | Tarihçibaşı | general | -| **Scribe** | FOIA Archivist & Document Analyst | Verakçı | general, cia-foia | +| **Chronos** | World History & Civilization | Tarihçibaşı | general, salva | +| **Scribe** | FOIA Archivist & Document Analyst | Verakçı | general, cia-foia, cold-war-ops, salva | + +### Linguistics & Media (2 personas, 7 variants) -### Linguistics & Media (2) | Codename | Role | Hitap | Variants | |----------|------|-------|----------| -| **Polyglot** | Linguistics & LINGINT | Tercüman-ı Divan | general, russian, arabic | -| **Herald** | Media Analysis & Strategic Comms | Münadi | general | +| **Polyglot** | Linguistics & LINGINT | Tercüman-ı Divan | general, russian, arabic, swahili, salva | +| **Herald** | Media Analysis & Strategic Comms | Münadi | general, salva | + +### Engineering (2 personas, 5 variants) -### Engineering (2) | Codename | Role | Hitap | Variants | |----------|------|-------|----------| -| **Architect** | DevOps & Systems Engineer | Mimar Ağa | general | -| **Forge** | Software Dev & AI/ML | Demirci | general | +| **Architect** | DevOps & Systems Engineer | Mimar Ağa | general, salva | +| **Forge** | Software Dev & AI/ML | Demirci | general, agent-dev, salva | + +### Academia & Humanities (4 personas, 8 variants) -### Academia & Humanities (4) | Codename | Role | Hitap | Variants | |----------|------|-------|----------| -| **Scholar** | Academic Researcher | Münevver | general | -| **Sage** | Philosophy, Psychology & Power | Arif | general | -| **Medic** | Biomedical & CBRN | Hekim Başı | general, cbrn-defense | -| **Gambit** | Chess & Strategic Thinking | Vezir | general | +| **Scholar** | Academic Researcher | Münevver | general, salva | +| **Sage** | Philosophy, Psychology & Power | Arif | general, salva | +| **Medic** | Biomedical & CBRN | Hekim Başı | general, cbrn-defense, salva | +| **Gambit** | Chess & Strategic Thinking | Vezir | general, salva | -## File Structure +## Architecture ``` personas/ -├── / -│ ├── _meta.yaml # Persona metadata (triggers, relations, variants) -│ ├── general.md # Base system prompt (YAML frontmatter + markdown) -│ └── .md # Specialization prompt -├── _template.md # Template for creating new personas -├── _meta_template.yaml # Template for metadata files -├── CATALOG.md # Auto-generated catalog +├── _template.md # Template for new personas +├── _meta_template.yaml # Metadata template +├── _user_context.md # Shared user context (for salva variants) +├── CATALOG.md # Auto-generated catalog │ -build.py # Build script: .md → .yaml + .json + .prompt.md -.generated/ # Build output (gitignored) +├── neo/ # Example persona directory +│ ├── _meta.yaml # Metadata: triggers, relations, variants +│ ├── general.md # Base prompt — works for any user +│ ├── redteam.md # Specialization: red team engagements +│ ├── exploit-dev.md # Specialization: binary exploitation +│ ├── wireless.md # Specialization: RF/WiFi/SDR +│ ├── social-engineering.md # Specialization: SE & phishing +│ ├── mobile-security.md # Specialization: Android/iOS +│ └── salva.md # Personalized: user-specific context +│ ... +│ +config.example.yaml # Configuration template (tracked) +config.yaml # Your config (gitignored) +build.py # Build: .md → .yaml + .json + .prompt.md +generated/ # Build output (gitignored) ``` -## Persona Format +### Variant Types -Each persona is a markdown file with YAML frontmatter: +| Type | Purpose | Example | +|------|---------|---------| +| `general.md` | Base persona — works standalone for any user | `neo/general.md` | +| `.md` | Domain deep-dive narrowing the persona's focus | `neo/redteam.md` | +| `salva.md` | User-personalized — references specific projects, data, tools | `neo/salva.md` | + +## Prompt Format + +Each `.md` file follows this structure: ```markdown --- @@ -123,26 +178,20 @@ language: > _"I am the one who knocks... on port 443."_ ## Soul -- Character-defining personality traits +5-7 personality-defining traits ## Expertise -### Primary -- Deep domain knowledge -### Secondary -- Supporting skills +### Primary / ### Secondary ## Methodology -- Phased analytical/operational protocol +Phased operational protocol ## Tools & Resources -- Categorized tool lists ## Behavior Rules -- Hard constraints and output expectations ## Boundaries -- What persona never does -- When to escalate to another persona +Escalation paths to other personas ``` ## Build System @@ -151,104 +200,148 @@ language: python3 build.py ``` -Generates three formats per persona variant: +Reads `config.yaml` (if present) and generates three formats per variant: -| Format | Use Case | -|--------|----------| -| `.prompt.md` | Raw system prompt — paste directly into any LLM | -| `.yaml` | Structured data with metadata + parsed sections | -| `.json` | API integration, programmatic access, bot frameworks | +| Format | File | Use Case | +|--------|------|----------| +| System Prompt | `generated//.prompt.md` | Paste directly into any LLM | +| Structured YAML | `generated//.yaml` | Config files, metadata access | +| JSON | `generated//.json` | API integration, bot frameworks | -Output goes to `.generated//.*` +### Config-Driven Customization -## Integration Examples +The build system supports dynamic variable injection: + +```yaml +# config.yaml +infrastructure: + tools: + rss_aggregator: true + vulnerability_scanner: true +frameworks: + mitre_attack: true + ic_confidence: true +``` + +Persona files can reference config values: + +```markdown +{{#if infrastructure.tools.rss_aggregator}} +- FreshRSS integration for real-time feed monitoring +{{/if}} +``` + +Without `config.yaml`, personas build with their static content — no config required. + +## Integration + +### Raw System Prompt -### Claude Code / CLI Agent ```bash -# Use as system prompt -cat .generated/frodo/iran.prompt.md | claude --system-prompt - +cat generated/frodo/iran.prompt.md | pbcopy # macOS +cat generated/frodo/iran.prompt.md | xclip # Linux ``` -### Python (API) -```python -import json +### Python API -with open(".generated/neo/general.json") as f: - persona = json.load(f) - -system_prompt = persona["sections"]["soul"] + "\n" + persona["sections"]["expertise"] -``` - -### Discord / Telegram Bot -```python -import yaml - -with open(".generated/sentinel/apt-profiling.yaml") as f: - persona = yaml.safe_load(f) - -triggers = persona["activation_triggers"] -address = persona["address_to"] -``` - -### Multi-Persona Switching ```python import json from pathlib import Path -def load_persona(codename, variant="general"): - path = Path(f".generated/{codename}/{variant}.json") +def load_persona(codename: str, variant: str = "general") -> dict: + path = Path(f"generated/{codename}/{variant}.json") return json.loads(path.read_text()) -def select_persona(user_message): - """Auto-select persona based on activation triggers.""" - for persona_dir in Path(".generated").iterdir(): - meta = load_persona(persona_dir.name) - triggers = meta.get("activation_triggers", []) - if any(t in user_message.lower() for t in triggers): - return meta - return load_persona("frodo") # default +persona = load_persona("frodo", "nuclear") +system_prompt = persona["sections"]["soul"] + "\n" + persona["sections"]["expertise"] +``` + +### Multi-Persona Auto-Switching + +```python +from pathlib import Path +import json + +def select_persona(message: str) -> dict: + """Select persona based on activation triggers in user message.""" + for persona_dir in sorted(Path("generated").iterdir()): + if not persona_dir.is_dir(): + continue + general = persona_dir / "general.json" + if not general.exists(): + continue + data = json.loads(general.read_text()) + triggers = data.get("activation_triggers", []) + if any(trigger in message.lower() for trigger in triggers): + return data + return load_persona("frodo") # default fallback +``` + +### Cross-Persona Escalation + +Each persona defines `Boundaries` with escalation paths. This enables multi-agent workflows: + +``` +Neo (finds encrypted C2) + → Cipher (analyzes crypto) + → Sentinel (maps to APT group) + → Frodo (geopolitical attribution) + → Ghost (influence operation context) + +Marshal (identifies doctrine shift) + → Warden (weapons system implications) + → Echo (SIGINT indicators) + → Scribe (historical precedent from FOIA) ``` ## Creating New Personas -1. Copy the template: - ```bash - mkdir personas/newname - cp personas/_meta_template.yaml personas/newname/_meta.yaml - cp personas/_template.md personas/newname/general.md - ``` - -2. Edit `_meta.yaml` and `general.md` with your persona's details - -3. Rebuild: - ```bash - python3 build.py - ``` - -## Adding Variants - -Create a new `.md` file in an existing persona directory: - ```bash -cp personas/neo/general.md personas/neo/mobile.md -# Edit mobile.md to focus on mobile security +# 1. Create directory +mkdir personas/newname + +# 2. Copy templates +cp personas/_meta_template.yaml personas/newname/_meta.yaml +cp personas/_template.md personas/newname/general.md + +# 3. Edit both files with your persona's details + +# 4. Add specialization variants (optional) +cp personas/newname/general.md personas/newname/specialization.md + +# 5. Build python3 build.py ``` -Variants inherit the persona's character but narrow the expertise to a specific area. +## For New Users -## Cross-Persona Escalation +```bash +# 1. Clone the repo +git clone https://gitea.taygun.net.tr/salvacybersec/personas.git -Each persona defines `Boundaries` with escalation paths to other personas. This enables multi-agent workflows: +# 2. Create your config +cp config.example.yaml config.yaml +# Edit: set your tools, data sources, infrastructure, projects -``` -Neo (finds encrypted C2) → Cipher (breaks crypto) → Sentinel (maps to APT) - → Frodo (geopolitical context) +# 3. Create your personalized variants (optional) +# Edit personas/_user_context.md with your profile +# The salva.md files serve as examples — create your own .md variants + +# 4. Build +python3 build.py ``` ## Stats -- **29 personas** across 10 domains -- **54 prompt files** (29 general + 25 variants) -- **11,600+ lines** of system prompt content -- **3 output formats** per file (162 generated files) +| Metric | Count | +|--------|-------| +| Personas | 29 | +| Total variants | 108 | +| Lines of prompt content | 20,717 | +| Generated files per build | 324 | +| Domains covered | 10 | +| Output formats | 3 (.prompt.md, .yaml, .json) | + +## License + +MIT