123 lines
4.4 KiB
Markdown
123 lines
4.4 KiB
Markdown
# 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. |