docs: add working principles to contributor docs

Document the Karpathy-style working principles in CLAUDE.md and add condensed references in contributor-facing docs so humans and agents follow the same guidance.

AGENTS.md

@@ -20,6 +20,15 @@ pnpm format                             # Prettier format
 
 Monorepo (pnpm) with packages: `core`, `cli`, `web`, and `plugins/*`. The web dashboard is a Next.js 15 app (App Router) with React 19 and Tailwind CSS v4. Data flows from `agent-orchestrator.yaml` through core's `loadConfig()` to API routes, served via SSR and a 5s-interval SSE stream. Terminal sessions use WebSocket connections to tmux PTYs. See CLAUDE.md for the full plugin architecture (8 slots), session lifecycle, and data flow.
 
+## Working Principles
+
+- **Think before coding.** State assumptions. Ask when unclear. Push back when a simpler approach exists.
+- **Simplicity first.** No speculative features. No abstractions for single-use code. Plugin slots are the extension point.
+- **Surgical changes.** Touch only what you must. Match existing style. Don't refactor things that aren't broken. Every changed line traces to the task.
+- **Goal-driven.** Define verifiable success criteria before implementing. Write tests that reproduce bugs before fixing them.
+
+Full guidelines with AO-specific context: see "Working Principles" in CLAUDE.md.
+
 ## Key Files
 
 - `packages/core/src/types.ts` — All plugin interfaces (Agent, Runtime, Workspace, etc.)

CLAUDE.md

@@ -131,6 +131,66 @@ Hash = SHA-256 of config directory (first 12 chars). Prevents collision across m
 2. Config prompt (project-specific rules from YAML)
 3. Rules files (optional `.agent-rules.md` from repo)
 
+## Working Principles
+
+These behavioral guidelines apply to every agent working on this codebase. They are not optional - they prevent the most common causes of PR rejection and rewrite.
+
+### Think Before Coding
+
+Don't assume. Don't hide confusion. Surface tradeoffs.
+
+- State assumptions explicitly. If uncertain, ask.
+- If multiple interpretations of a task exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+- When editing `lifecycle-manager.ts` or `session-manager.ts`: state which invariants your change preserves. These files have subtle state dependencies.
+
+### Simplicity First
+
+Minimum code that solves the problem. Nothing speculative.
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- Plugin slots are the extension point. Don't add configuration surface when a new plugin is the right answer.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+### Surgical Changes
+
+Touch only what you must. Clean up only your own mess.
+
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If your changes create orphans (unused imports, dead variables), remove them.
+- Don't remove pre-existing dead code unless asked.
+- Every changed line should trace directly to the task description.
+
+This is especially critical in:
+- `types.ts` - changing an interface breaks every plugin. Minimize surface changes.
+- `globals.css` - tokens are consumed across 50+ components. Don't rename casually.
+- `lifecycle-manager.ts` - state transitions have implicit dependencies. Document why a transition is safe.
+
+### Goal-Driven Execution
+
+Define success criteria. Loop until verified.
+
+Transform tasks into verifiable goals:
+- "Add a new status" -> "Add to enum, update `isTerminalSession`, add to dashboard column mapping, write tests for all three"
+- "Fix the bug" -> "Write a test that reproduces it, then make it pass"
+- "Refactor X" -> "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+
+[Step] -> verify: [check]
+[Step] -> verify: [check]
+[Step] -> verify: [check]
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
 ## Conventions
 
 ### Code Style

CONTRIBUTING.md

@@ -205,6 +205,18 @@ Your plugin package must satisfy the contract in [`docs/PLUGIN_SPEC.md`](docs/PL
 
 See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for the full reference. The short version:
 
+### Behavioral Guidelines
+
+Beyond syntax and style, follow these principles:
+
+- **State assumptions explicitly** - if a task is ambiguous, present interpretations rather than guessing.
+- **Minimum viable change** - no speculative features, no unused abstractions, no formatting changes outside your diff.
+- **Every changed line traces to the task** - if you can't explain why a line changed, revert it.
+- **Write a failing test first** - for bug fixes, reproduce the bug in a test before implementing the fix.
+- **Don't refactor unrelated code** - mention dead code you spot, don't delete it.
+
+These match the "Working Principles" section in CLAUDE.md. AI agents working on this repo are instructed to follow these same rules.
+
 **TypeScript**
 
 - ESM modules, `.js` extensions on local imports

docs/DEVELOPMENT.md

@@ -72,6 +72,17 @@ Activity states (orthogonal to lifecycle): `active`, `ready`, `idle`, `waiting_i
 | `packages/core/src/observability.ts`     | Correlation IDs, structured logging, metrics    |
 | `packages/core/src/paths.ts`             | Hash-based path and session name generation     |
 
+### Working Principles
+
+These apply to both human contributors and AI agents:
+
+1. **Think before coding.** If a task is ambiguous, ask for clarification. If multiple approaches exist, present the tradeoff.
+2. **Minimum code.** No speculative features. No abstractions for code used once. Plugin slots exist for extensibility - use them instead of config proliferation.
+3. **Surgical diffs.** Don't touch files outside your change scope. Don't reformat adjacent code. Match existing patterns even if you prefer differently. Every changed line should trace to a specific requirement.
+4. **Verifiable goals.** Before implementing, state what "done" looks like and how to verify it. For bug fixes: write a test that reproduces the bug first.
+
+For AI agent-specific guidance (including high-risk files like `types.ts`, `lifecycle-manager.ts`, `globals.css`), see CLAUDE.md -> Working Principles.
+
 ---
 
 ## Getting Started