165 lines
5.1 KiB
Markdown
165 lines
5.1 KiB
Markdown
# 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
|
|
|
|
```markdown
|
|
# 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?** |