5.1 KiB

Raw Blame History

Clavitor Agent Handbook — Section Count Analysis

Question: What is the optimal number of sections?

Analysis: The content naturally clusters by reading pattern, not arbitrary grouping.

Content Inventory by Reading Pattern

Pattern	When read	Content
Onboard	First day	Foundation First, KISS, DRY, personas, cardinal rules, threat model
Daily	Every work session	Git workflow, PRs, checklist
Emergency	When things break	Incident response, token compromise, lockouts
Policy	When questions arise	Compliance, retention, data governance
Project	Before touching code	Subproject specifics (vault, CLI, crypto, etc.)

That's 5 natural reading patterns.

Option Comparison

Option A: 3 Sections (original proposal)

I. Who We Are      (onboard + emergency + policy mixed)
II. How We Work    (daily + emergency mixed)
III. What We Build (project)

Problem: Emergency procedures (read rarely, under stress) mixed with culture (read once). Workflow (daily) mixed with incident response (emergency).

Option B: 4 Sections

I. Culture & Principles      (onboard)
II. Security & Threat Model    (onboard + reference)
III. Workflow & Operations     (daily + emergency mixed)
IV. Subproject Reference       (project)

Problem: Still mixing daily workflow with emergency operations.

Option C: 5 Sections (RECOMMENDED)

I. Culture              (onboard)
II. Security            (onboard + reference)
III. Workflow           (daily)
IV. Operations          (emergency + policy)
V. Subprojects          (project)

Benefits:

Each section has ONE reading pattern
Clear mental model: "I need emergency help → Section IV"
Culture and Security are separate (Security is technical, Culture is values)
Workflow is daily, Operations is reference
Can grow: add subprojects to V without touching I-IV

Option D: 6 Sections

I. Culture
II. Security
III. Workflow
IV. Emergency Response
V. Compliance & Policy
VI. Subprojects

Problem: Emergency and Policy are both "read as needed" — splitting them creates a thin Section V (compliance is ~50 lines).

Option E: 7+ Sections

Too granular. Hard to remember which section contains what. Defeats the purpose of a handbook.

Final Recommendation: 5 Sections

# Clavitor Agent Handbook

## Section I — Culture
Who we are, what we believe, how we treat foundations.
- Foundation First, KISS, DRY, Q&D is research
- Error handling philosophy (every if needs an else)
- Agent personas (Sarah, Charles, Maria, James, Emma, Arthur, Victoria, Luna, Thomas, Hugo, Hans, George)
- When principles conflict (escalation, violation handling)

## Section II — Security
The threat model and cardinal rules. Non-negotiable.
- Threats A, B, C
- Cardinal Rules #1-4 (Loud failures, dumb server, trust browser, FIPS 140-3)
- Exceptionally rare terms (master_key, L3, P3)
- Cryptographic hygiene

## Section III — Workflow
How we work together day-to-day.
- Git workflow (commit format, branches, push guidelines)
- Agent-authored PRs (template, review process)
- Daily review checklist (LLM-driven verification)

## Section IV — Operations
How we run the service and handle incidents.
- Incident Response (agent lock/unlock, token compromise)
- Emergency procedures (owner lockout, vault compromise)
- Data retention (paying vs non-paying)
- Compliance (cross-border, Zurich anchor)
- Adding new principles (format, deprecation)

## Section V — Subprojects
Domain-specific guidance. Read before touching that code.
- clavis-vault (Sarah)
- clavis-cli (Charles)
- clavis-crypto (Maria)
- clavis-chrome/firefox/safari (James)
- clavitor.ai/admin (Emma)
- clavis-telemetry (Hans)
- Localization (English-first, RTL not priority)

Size Targets (with hard limits)

Section	Target	Hard Limit	Escape Valve
I. Culture	250 lines	400	Stop adding philosophy
II. Security	200 lines	300	Move threat details to `docs/THREAT-MODEL.md`
III. Workflow	300 lines	500	Move checklists to subproject CLAUDE.md
IV. Operations	350 lines	500	Move incident playbooks to `docs/RUNBOOKS/`
V. Subprojects	300 lines	600	Add new subproject = add subsection
Total	1,400	2,300	If total > 2,000, split Section V to `docs/SUBPROJECTS.md`

Reading Guide (for agents)

Situation	Read
First time here	Section I completely, skim II-IV
About to make a commit	Section III (Git workflow)
Security alert / incident	Section IV (Operations)
Touching vault code	Section V: clavis-vault
Not sure who you are	Section I: Agent personas
Principles conflict	Section I: When principles conflict
Adding a new principle	Section IV: Adding new principles

Conclusion: 5 sections matches the 5 reading patterns. Each section has a clear purpose and audience. Not too many to remember, not too few to be cluttered.

Does 5 sections feel right?

5.1 KiB Raw Blame History