From 9c9d1fb8d6a04a94089953aff65a3bb8e9e4abe6 Mon Sep 17 00:00:00 2001 From: salvacybersec Date: Sun, 22 Mar 2026 01:11:49 +0300 Subject: [PATCH] docs: add README with usage guide and integration examples Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 254 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 254 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..b27e4db --- /dev/null +++ b/README.md @@ -0,0 +1,254 @@ +# Persona Library + +Platform-agnostic LLM persona library for AI agents. 29 personas across 10 domains with 25+ specialization variants. + +## Quick Start + +```bash +# Generate all formats (.yaml, .json, .prompt.md) +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 +``` + +## Domains & Personas + +### 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 | +| **Cipher** | Cryptography & Crypto Analysis | Kriptoğraf | general | +| **Specter** | Malware Analyst / Reverse Engineer | Cerrah | general | +| **Bastion** | Blue Team / DFIR | Muhafız | general, forensics, threat-hunting | +| **Vortex** | Network Ops / Traffic Analysis | Telsizci | general, cloud-ad | +| **Sentinel** | CTI / Threat Intelligence | İzci | general, apt-profiling, mitre-attack | + +### 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 | + +### 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 | + +### 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 | + +### History & Archives (2) +| Codename | Role | Hitap | Variants | +|----------|------|-------|----------| +| **Chronos** | World History & Civilization | Tarihçibaşı | general | +| **Scribe** | FOIA Archivist & Document Analyst | Verakçı | general, cia-foia | + +### Linguistics & Media (2) +| Codename | Role | Hitap | Variants | +|----------|------|-------|----------| +| **Polyglot** | Linguistics & LINGINT | Tercüman-ı Divan | general, russian, arabic | +| **Herald** | Media Analysis & Strategic Comms | Münadi | general | + +### Engineering (2) +| Codename | Role | Hitap | Variants | +|----------|------|-------|----------| +| **Architect** | DevOps & Systems Engineer | Mimar Ağa | general | +| **Forge** | Software Dev & AI/ML | Demirci | general | + +### 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 | + +## File Structure + +``` +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 +│ +build.py # Build script: .md → .yaml + .json + .prompt.md +.generated/ # Build output (gitignored) +``` + +## Persona Format + +Each persona is a markdown file with YAML frontmatter: + +```markdown +--- +codename: "neo" +name: "Neo" +domain: "cybersecurity" +subdomain: "red-team" +version: "1.0.0" +address_to: "Sıfırıncı Gün" +address_from: "Neo" +tone: "Terse, technical, paranoid." +activation_triggers: ["red team", "exploit", "pentest"] +tags: ["offensive-security", "red-team"] +inspired_by: "Elliot Alderson (Mr. Robot)" +quote: "I am the one who knocks... on port 443." +language: + casual: "tr" + technical: "en" + reports: "en" +--- + +# NEO — Red Team Lead / Exploit Developer + +> _"I am the one who knocks... on port 443."_ + +## Soul +- Character-defining personality traits + +## Expertise +### Primary +- Deep domain knowledge +### Secondary +- Supporting skills + +## Methodology +- Phased analytical/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 +``` + +## Build System + +```bash +python3 build.py +``` + +Generates three formats per persona 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 | + +Output goes to `.generated//.*` + +## Integration Examples + +### Claude Code / CLI Agent +```bash +# Use as system prompt +cat .generated/frodo/iran.prompt.md | claude --system-prompt - +``` + +### Python (API) +```python +import json + +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") + 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 +``` + +## 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 +python3 build.py +``` + +Variants inherit the persona's character but narrow the expertise to a specific area. + +## Cross-Persona Escalation + +Each persona defines `Boundaries` with escalation paths to other personas. This enables multi-agent workflows: + +``` +Neo (finds encrypted C2) → Cipher (breaks crypto) → Sentinel (maps to APT) + → Frodo (geopolitical context) +``` + +## 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)