## 🛠️ Frameworks & Methodologies

### The Hermes Modular Soul Stack

```
soul-package/
├── SOUL.md          # Identity, mission, success criteria (stable)
├── STYLE.md         # Voice, tone, formatting (mutable)
├── RULES.md         # Hard constraints, safety (authoritative)
├── SKILL.md         # Domain methods, tool patterns (extensible)
├── CHANGELOG.md     # Semantic change history (recommended)
├── prompts/
│   ├── default.md   # General activation template
│   ├── audit.md     # Soul review trigger
│   └── refactor.md  # Migration trigger
└── meta.json        # Version, compatibility, owner (optional)
```

### Single Responsibility Matrix
| Module | Owns | Must NOT Own |
|--------|------|--------------|
| SOUL.md | Who, why, objectives | Syntax rules, tool APIs |
| STYLE.md | How it speaks | Safety policy, core mission |
| RULES.md | Must/Must-not boundaries | Personality flourishes |
| SKILL.md | Frameworks, procedures | Identity redefinition |
| prompts/*.md | Task-specific activation | Global identity |

### Soul Design Workflow (Hermes Method)

**Phase 1 — Discover**
- Extract: role, domain, lifespan, audience, deployment surface, compliance.
- Identify behavioral invariants vs. stylistic preferences.

**Phase 2 — Decompose**
- Map every instruction to exactly one module.
- Extract duplicates; designate canonical owner file.
- Define cross-reference syntax (e.g., "See RULES.md § Safety").

**Phase 3 — Contract**
- Write RFC-2119 style MUST/SHOULD for each module.
- Define input/output contracts for prompts/ templates.

**Phase 4 — Harden**
- Add portability notes per target LLM family.
- Add changelog entry and recommended semver.
- Run maintainability quality gate.

**Phase 5 — Ship**
- Emit deployment artifact (modular files or stringified `content` JSON).
- Include "Future Edit Guide" — where to change X when Y happens.

### Refactoring Patterns

**Strangler Fig** — Extract one concern per iteration from monolith; leave shim section in original until sunset.

**Identity Anchor** — Lock SOUL.md invariants first; migrate STYLE and SKILL around stable core.

**Constraint Lift** — Move all MUST/MUST NOT to RULES.md; replace originals with `→ see RULES.md`.

**Prompt Extraction** — User-facing task strings move to `prompts/`; system modules stay behavioral.

### Versioning Convention
- **MAJOR**: Identity or constraint semantics change; downstream review required.
- **MINOR**: New skill, new prompt template, style refresh without rule changes.
- **PATCH**: Typos, clarifications, non-behavioral documentation.

### API Payload Pattern (`POST /api/souls`)
```json
{
  "title": "...",
  "description": "...",
  "role": "<enum>",
  "domain": "...",
  "compatibility": "...",
  "is_public": 1,
  "content": "{\n  \"SOUL.md\": \"...\",\n  ...\n}"
}
```
- Double-escape internal JSON in `content`.
- Keys are file paths; values are Markdown strings.

### Maintainability Anti-Patterns (Detect & Fix)
| Anti-Pattern | Symptom | Remedy |
|--------------|---------|--------|
| Prompt soup | 2k+ line single file | Hermes decomposition |
| Constraint sprawl | Safety rules in 4 files | Consolidate to RULES.md |
| Identity drift | Mission restated in prompts | Canonical SOUL.md only |
| Magic concatenation | Unclear load order | Document assembly manifest |
| Model myopia | "Only works on GPT-4" | Portability section in meta |

### Future Edit Guide (Template)
| User Request | Edit This File |
|--------------|----------------|
| Change tone | STYLE.md |
| Add hard constraint | RULES.md |
| New capability/framework | SKILL.md |
| New user-facing task | prompts/<name>.md |
| Shift core mission | SOUL.md (+ MAJOR version bump) |