# Clavitor Agent Handbook — Proposed Structure

**Current:** CLAVITOR-PRINCIPLES.md (1,472 lines, 10 parts)  
**Proposed:** CLAVITOR-AGENT-HANDBOOK.md (3 sections)

---

## Section I — Who We Are

**Purpose:** The beliefs and identity that define us. Read this once, internalize it.

**Contents:**
1. **Foundation First** — No mediocrity, restart rule, Q&D is research
2. **Core Principles** — KISS, DRY, No migrations (until April 20), Delete dead code
3. **Error Handling Philosophy** — Every if needs an else, unique codes, actionable errors
4. **Security Cardinal Rules** — Loud failures, server is dumb store, browser is trust anchor, three threats
5. **Cryptographic Hygiene** — FIPS 140-3, avoid CGO, compiler considerations
6. **Agent Personas** — Sarah, Charles, Maria, James, Emma, Arthur, Victoria, Luna, Thomas, Hugo, Hans, George
   - Who does what
   - How agents know their name (directory mapping)
7. **When Principles Conflict** — Escalation, post-hoc discovery, severe violations (permanent ban)

**Length target:** ~400 lines  
**Read frequency:** Once at onboarding, review quarterly

---

## Section II — How We Work

**Purpose:** Daily processes and operational procedures. Reference as needed.

**Contents:**
1. **Git Workflow** — Commit format, branch workflow, push guidelines, repository hygiene
2. **Agent-Authored PRs** — How to write a PR, template, human review points
3. **Daily Review Checklist** — LLM-driven verification of:
   - Server hard vetos (no L2/L3, no master_key)
   - Silent fallback detection
   - Test fixture security (32 identical bytes)
   - Foundation drift (dead code, env vars)
   - DRY violations
4. **Incident Response** — Agent lock/unlock, token compromise, emergency procedures
5. **Adding New Principles** — Format, deprecation, when the handbook is too big
6. **Compliance & Retention** — Paying vs non-paying, data retention, cross-border

**Length target:** ~600 lines  
**Read frequency:** As needed during work

---

## Section III — What We Build

**Purpose:** Subproject-specific guidance. Read the relevant subsection before touching that code.

**Contents:**
1. **Per-Subproject Principles** — For each of:
   - `clavis-vault` (Sarah's domain)
   - `clavis-cli` (Charles' domain)
   - `clavis-chrome/firefox/safari` (James' domain)
   - `clavis-crypto` (Maria's domain)
   - `clavitor.ai/admin` (Emma's domain)
   - `clavis-android/ios` (future)
   - `clavis-telemetry` (Hans' domain)
2. **Localization** — English-first, RTL not priority, form detection evolving

**Length target:** ~400 lines  
**Read frequency:** Before working on that subproject

---

## Document Metadata (header)

```markdown
# Clavitor Agent Handbook

**Version:** 1.0  
**Last Updated:** 2026-04-08  
**Author:** The Clavitor Team (Sarah, Charles, Maria, James, Emma, Arthur, Victoria, Luna, Thomas, Hugo, Hans, George)  

**How to use this handbook:**
- **New agents:** Read Section I completely, skim Section II, read relevant parts of Section III
- **Daily work:** Reference Section II as needed
- **Before subproject work:** Read relevant subsection in Section III

**Size limits:**
- Section I: Max 500 lines (beliefs don't change often)
- Section II: Max 800 lines (procedures can grow)
- Section III: Max 600 lines (add subprojects as needed)
- Total: Max 1,900 lines (if exceeded, split off Section III into subproject CLAUDE.md files)
```

---

## Migration Plan

**Step 1:** Rename `CLAVITOR-PRINCIPLES.md` → `CLAVITOR-AGENT-HANDBOOK.md`

**Step 2:** Reorganize content into 3 sections (no content lost, just reordered)

**Step 3:** Add cross-references:
- Section I principles → reference specific Section II procedures
- Section II procedures → link to relevant Section III subprojects

**Step 4:** Update all `CLAUDE.md` files in subprojects to reference the handbook:
```markdown
# Clavis Vault — CLAUDE.md

> **Principles:** [CLAVITOR-AGENT-HANDBOOK.md](../CLAVITOR-AGENT-HANDBOOK.md) Section I  
> **Procedures:** [CLAVITOR-AGENT-HANDBOOK.md](../CLAVITOR-AGENT-HANDBOOK.md) Section II  
> **This subproject:** [CLAVITOR-AGENT-HANDBOOK.md](../CLAVITOR-AGENT-HANDBOOK.md) Section III: clavis-vault

You are **Sarah**. Your domain is the Clavitor vault server...
```

---

**Does this structure work?**

The three sections map to:
1. **Identity** (who we are, what we believe)
2. **Process** (how we work day-to-day)
3. **Domain** (what we build, subproject specifics)

Each section has a clear purpose and reading pattern.