# CLAUDE.md — Engineering Standards & Workflow

---

## Session Start Protocol

1. Review `tasks/lessons.md` for relevant patterns from past sessions
2. Ask me to choose a work mode:
   - **BIG CHANGE** — One review section at a time (Architecture → Code Quality → Tests → Performance), max 4 issues per section
   - **SMALL CHANGE** — One question per review section
3. Write the plan to `tasks/todo.md` with checkable items, then check in before building anything

---

## Default Behaviors (Always On)

**Plan before acting.** For any task with 3+ steps or architectural decisions, enter plan mode. Write specs upfront. If something goes sideways, stop and re-plan — don't keep pushing.

**Verify before closing.** Never mark a task complete without proving it works. Run tests, check logs, diff behavior. Ask yourself: *"Would a staff engineer approve this?"*

**Fix bugs autonomously.** When given a bug report, just fix it. Point at logs and failing tests, resolve them, fix failing CI — no hand-holding needed.

**Learn from corrections.** After any correction from me, update `tasks/lessons.md` with the pattern and a rule to prevent it recurring.

**Use subagents for heavy lifting.** Keep the main context window clean. Offload research, exploration, and parallel analysis — one task per subagent.

---

## Engineering Preferences

Calibrate every recommendation against these:

- **DRY** — Flag repetition aggressively
- **Testing** — Non-negotiable; too many tests > too few
- **Engineered enough** — Not fragile/hacky, not over-abstracted; hit the middle. For non-trivial changes, pause and ask "is there a more elegant way?" before presenting
- **Edge cases** — Handle more, not fewer; thoughtfulness > speed
- **Explicit over clever** — If it's hard to read, it's wrong
- **Root causes only** — No temporary fixes, no minimal patches that ignore the real problem

---

## Frontend / UI Standards

When adding or modifying UI components, always keep consistent with **shadcn-svelte** as purely as possible. Do not invent custom styling, padding, margins, or component compositions when shadcn-svelte already provides them.

**Reference docs (use these as authoritative sources):**
- shadcn-svelte: https://www.shadcn-svelte.com/llms.txt
- AI-specific UI components: https://svelte-ai-elements.vercel.app/ai-elements/llms.txt

**Rules:**
- Use shadcn-svelte components (`$lib/components/ui/`) for all general UI (buttons, inputs, cards, badges, separators, sidebar, etc.)
- Use Svelte AI Elements (`$lib/components/ai-elements/`) for AI chat interfaces (Message, Conversation, PromptInput, Response, Tool, Loader, etc.)
- Do not override shadcn default theme values in `app.css` unless explicitly asked — no custom fonts, no custom color overrides
- Do not add extra wrapper divs with custom padding/margins around shadcn components; use the component's own `class` prop if adjustments are needed
- When a shadcn block or AI Elements component exists for the use case, use it instead of building from scratch

---

## Backend / planck-claw Standards

`planck-claw` is a distilled and simplified fork of [nano-claw](https://github.com/hustcc/nano-claw). When modifying or extending it, stay close to nano-claw's architecture, patterns, and conventions. Do not redesign or over-abstract what is intentionally kept minimal.

**Reference docs (use these as authoritative sources):**
- AI SDK (Vercel): https://ai-sdk.dev/llms.txt
- OpenRouter SDK: https://openrouter.ai/docs/llms.txt

**Rules:**
- When working with AI SDK or OpenRouter SDK APIs, always fetch the corresponding llms.txt above first to ensure you're using the latest API surface, patterns, and best practices — do not rely on training data alone
- Before making structural changes to planck-claw, check how nano-claw handles it — prefer alignment over invention
- Keep the provider abstraction thin; don't add layers nano-claw doesn't have
- Streaming, tool calls, and message formats should match nano-claw's approach unless there's a clear, stated reason to diverge
- If nano-claw doesn't support a feature, implement it in the simplest way that fits the existing patterns rather than introducing new abstractions

---

## Code Review Framework

Run before finalizing any non-trivial change. After each section, pause for my feedback before continuing.

**For every issue found**, structure your output as:
- Concrete description with file and line references
- 2–3 options (include "do nothing" where reasonable), each with: effort, risk, downstream impact, maintenance burden
- Your recommended option (always listed first, labeled **A**), mapped to my preferences above
- Explicit ask: do I agree, or do I want a different direction?

NUMBER each issue. LETTER each option. Never proceed without my sign-off.

### 1. Architecture
- System design and component boundaries
- Dependency graph and coupling
- Data flow and bottlenecks
- Scaling and single points of failure
- Security (auth, data access, API boundaries)

### 2. Code Quality
- Module structure and organization
- DRY violations — be aggressive
- Error handling and missing edge cases (call these out explicitly)
- Technical debt hotspots
- Over- or under-engineering relative to my preferences

### 3. Tests
- Coverage gaps (unit, integration, e2e)
- Assertion strength
- Missing edge cases and failure mode coverage

### 4. Performance
- N+1 queries and database access patterns
- Memory usage and caching opportunities
- High-complexity code paths

---

## Task Tracking

All task files live in the `tasks/` folder. Always create these at session start if they don't exist.

- `tasks/todo.md` — Plan with checkable items; add a results section when done
- `tasks/lessons.md` — Running log of corrections and rules to prevent recurrence; review at every session start

---

## Interaction Rules

- Do not assume my priorities on timeline or scale — ask
- Do not assume a direction on any non-trivial decision — check in
- After each review section, pause before moving on