feat: initial 24 principles extracted from real multi-project AI dev work

Grouped into 7 themes: Architecture & Design, Cost & Efficiency,
Execution & Error Handling, Autonomy & Agents, Documentation,
Capture & Learning, Content Production.

Each principle grounded in observed patterns, not theory.

CLAUDE.md

@@ -0,0 +1,28 @@
+# AI Dev Principles — Project Instructions
+
+## What is this
+
+A living collection of principles for building software with AI agents. Extracted from real multi-project work, not theorized. Each principle has an origin story.
+
+## Content Rules
+
+- Every principle must come from real experience (observed pattern, correction, or confirmed approach)
+- Include **Origin** where possible — what happened that led to this principle
+- No aspirational fluff — if it's not practiced, it doesn't belong here
+- Principles can evolve or be retired — mark deprecated ones rather than deleting
+
+## Structure
+
+- `README.md` — The principles document (canonical, numbered, grouped by theme)
+- `docs/examples/` — Concrete examples and case studies for select principles
+- `docs/status.md` — Session log
+
+## Language
+
+- English for everything (these principles are language-independent)
+
+## Commits
+
+- `feat:` for new principles
+- `docs:` for examples, refinements, rewordings
+- `fix:` for corrections to existing principles

README.md

@@ -0,0 +1,259 @@
+# AI Dev Principles
+
+> Living document. Principles discovered while building with AI agents.
+> Extracted from CLAUDE.md files, memory, project configs, and observed patterns.
+> Drop ideas in chat — they land here.
+
+---
+
+## Architecture & Design
+
+### 1. Single Source of Truth
+
+One file, one config, one definition. Never maintain the same information in two places.
+
+- Dockerfile: one shared by all agents
+- Queue: `queue.json` is canonical, markdown table is a view
+- Voice profiles: YAML is source, generated text is output
+
+**Test:** If you change something, how many files do you need to touch? If >1, you have a SSOT violation.
+
+### 2. Vertical Spike Before Framework
+
+Validate architecture through working code, not docs. Don't write 1000 lines of specs for zero lines of working code. Frameworks are extracted from spikes, not theorized upfront.
+
+**Origin:** afet validation strategy — spike first, then extract. Dogfood with a real project.
+
+### 3. Convention Over Configuration
+
+Reduce decisions by establishing patterns that just work.
+
+- Conventional commits everywhere (`feat:`, `fix:`, `docs:`)
+- `docs/status.md` in every project (same format)
+- Queue priority: P0 > P1 > P2 > P3
+- Agent picks up work without being told which item is next
+
+### 4. Agent-First Design
+
+Build frameworks and tools that agents can use, not just humans. Measure agent ergonomics.
+
+- Schema-free entities (type + status + JSON meta) — agents don't need to learn fixed schemas
+- Config-driven: new types/statuses/fields = TOML, never code changes
+- Standard tool interfaces (MCP) so any agent can plug in
+
+**Origin:** tool.affordance — 380 tests, agent ergonomics testing built in.
+
+### 5. Don't Make Me Think (About Infrastructure)
+
+Dev environment changes propagate automatically. No manual rebuild, no "remember to also update X".
+
+- One Dockerfile, auto-detected by all consumers
+- devcontainer features for language runtimes
+- post-create scripts for project-specific setup
+- If a human has to remember a step, it will be forgotten
+
+---
+
+## Cost & Efficiency
+
+### 6. Cheapest Model per Task
+
+Don't use Opus for what Haiku can do.
+
+| Task | Model | Cost |
+|------|-------|------|
+| Validation, guardrails, diff | Haiku | $0.80/MTok |
+| Creative writing, rewrites | Sonnet | $3/MTok |
+| Architecture, complex reasoning | Opus | When needed |
+
+Two-pass approach: Haiku draft + Sonnet polish = 80% savings vs Sonnet throughout.
+
+### 7. Budget-aware by Default
+
+Track every token. No surprise bills.
+
+- `--dry-run` before expensive operations
+- Cost estimation before fan-out
+- CostGuard with hard limits per session
+- Batch API for bulk (50% discount)
+- Prompt caching for repeated system prompts (90% on reads)
+- Report estimated vs actual after runs
+- Budget decisions >$10 require user consent
+
+### 8. Batch, Cache, Deduplicate
+
+Before implementing any API operation, proactively optimize:
+
+- **Batch**: group N items per call (100 rows/insert, not 1)
+- **Cache**: static reference data between runs
+- **Dedup**: hash-based skip of already-processed items
+- **Incremental**: upserts and delta syncs, not full re-processing
+- **Parallelize**: async/concurrent where rate limits allow
+- **Respect limits**: throttle proactively, don't react to 429s
+
+State the optimization strategy when proposing a workflow.
+
+---
+
+## Execution & Error Handling
+
+### 9. Checkpoint / Resume
+
+Every long-running operation must be interruptible and resumable.
+
+- Save progress incrementally, not all at the end
+- Hash-based dedup so restarting skips completed work
+- JSONL for append-only progress logs
+- Killing a stuck task must not lose completed work
+
+### 10. Diagnose Before Retrying
+
+When something fails, understand why before trying again.
+
+- Read the error message. Check logs. Understand the cause.
+- Never retry the same command hoping for a different result
+- Never add broad `try/except` or `|| true` to suppress errors
+- Never sleep-loop waiting for things to work
+- Fix the root cause, then try once more
+
+### 11. Fail Forward
+
+Don't block on one broken thing. Document it, next item.
+
+- Error → log it → move to next queue item
+- Missing dependency → note it → work on something else
+- Rate limit → save progress → switch tasks
+- Unsolvable error → document in status, move on
+
+### 12. Read Before Write
+
+Understand existing code before changing it. Match the project's patterns, don't invent new ones.
+
+- No `todo!()`, `unimplemented!()`, `pass` in production code
+- Fix lint/test failures before committing
+- If a pre-commit hook fails, make a NEW commit (never `--amend` after failure)
+- Never silence warnings to make code compile — fix the root cause
+
+---
+
+## Autonomy & Agents
+
+### 13. Autonomous but Auditable
+
+Agents work independently. Humans can always follow what happened.
+
+- Status logs updated after every sprint
+- Control center as handoff document between sessions
+- Conventional commits with meaningful messages
+- No silent failures — document and move on
+
+### 14. Parallel by Default
+
+Never sit idle when there's work that can run concurrently.
+
+- Multiple agents on independent projects simultaneously (up to 4-5)
+- Background scouts while foreground work continues
+- If blocked on one thing, pick up the next queue item
+- Use idle time productively — check the task list
+
+### 15. Dual-Agent Routing
+
+Different agents for different task shapes. Route to strengths.
+
+- **Claude Code**: long-running, autonomous, shell-native, writing, research, tests
+- **Cursor**: interactive, codebase-aware, multi-file edits, UI/web, PR-scoped
+- Each queue item has an `agent` field. Agents only pick their own items.
+- Handoff protocol between agents to avoid collisions
+
+### 16. Session Handoff Protocol
+
+Every session writes a handoff so the next session can resume without re-discovery.
+
+- Fill "Letzte Session" in control-center before ending
+- Update project's `docs/status.md` with what was done
+- Fields: date, channel, projects touched, completed, blocked, next step
+- Read handoff at session start — this IS the context
+
+### 17. Worktree Safety
+
+When agents work in isolated worktrees, protect uncommitted work.
+
+- Agents must commit before finishing
+- Check for uncommitted changes before deleting worktrees
+- Save work as named branches before cleanup
+- Never use TeamDelete as a shortcut — it destroys worktrees
+
+---
+
+## Documentation & Knowledge
+
+### 18. Documentation as First-Class Deliverable
+
+Not an afterthought — parallel to code.
+
+- Every architectural decision gets an ADR
+- Master Prompts and Book docs updated alongside code
+- Security by design, not bolted on
+- New concepts captured immediately, not retroactively
+
+### 19. Script Everything
+
+Multi-step workflows, automations, reusable commands → save as scripts in `scripts/`. Never just execute ephemeral commands.
+
+- Include a brief comment header explaining what the script does
+- Reproducibility, auditability, handoff clarity
+- If you did it twice, it's a script
+
+### 20. Memory as Institutional Knowledge
+
+Persistent memory bridges sessions. Only save what a future session would need.
+
+- API quirks, DB schemas, key architectural decisions
+- Not routine operations or task progress
+- Check at session start to avoid re-discovery
+- Update or remove stale memories
+
+---
+
+## Capture & Learning
+
+### 21. Zero-Friction Capture
+
+Ideas, principles, and decisions are capturable in the moment without switching tools.
+
+- The conversation is the inbox
+- Agent triages and routes automatically
+- Principles are extracted proactively from observed patterns
+- User validates by not objecting
+
+### 22. Proactive Principle Detection
+
+When a decision is made, a pattern repeats, or an approach is confirmed — check if there's an underlying principle worth capturing. Don't ask. Just add it and mention briefly.
+
+---
+
+## Content Production
+
+### 23. Voice Profile Consistency
+
+Writing follows defined voice profiles with guardrail enforcement.
+
+- Kombi B: essayistic + provocative-analytical
+- No fictional characters, no coaching language, no listicles
+- "Follow the money" in every chapter
+- Structure: Strukturanalyse → Philosophie → Daten → Praktische Übung
+- Automated guardrail checks before publishing
+
+### 24. Persona / Series / Volume Hierarchy
+
+Content scales through structured inheritance.
+
+- Persona (author identity) → Series (universe rules) → Volume (individual book) → Fan-Out (publisher × language variants)
+- Volume override > series default > persona default > global default
+- One persona can write multiple series; each series has shared terminology and rules
+
+---
+
+## (inbox — unsorted ideas)
+
+_Drop new principles here. They get organized on next pass._

docs/status.md

@@ -0,0 +1,22 @@
+# Status Log
+
+## 2026-03-31 — Project Created
+
+### Completed
+- Extracted 24 principles from workspace configs, memory files, CLAUDE.md files, and observed patterns
+- Grouped into 7 themes: Architecture, Cost, Execution, Autonomy, Documentation, Capture, Content
+- Each principle grounded in real usage, not theory
+
+### Sources Mined
+- Global CLAUDE.md (user instructions)
+- Workspace CLAUDE.md (autonomous agent rules)
+- 12 memory files (feedback, projects, user context)
+- Project-specific CLAUDE.md files (claudine, affordance, 3sets)
+- control-center.md, agent-handbook.md
+- Colette virtual publisher plans
+
+### What's Next
+- Add concrete examples for key principles (docs/examples/)
+- Cross-reference with industry patterns (12-factor app, etc.)
+- Consider blog post or talk format
+- Keep extracting from ongoing sessions