clavitor/HANDBOOK-STRUCTURE-PROPOSAL.md

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)

# 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:

# 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.