# AI Assistant Instructions

---

## ⚠️ MANDATORY: READ BEFORE ANY OPERATION ⚠️

**STOP.** Before you do ANYTHING in this codebase, you MUST read these files:

### Required Reading (`.claude/standards/`)

| File | Purpose | Read When |
|------|---------|-----------|
| **`.claude/standards/CLAUDE_CODE_RULES.md`** | Non-negotiable rules (git, venv, testing, logging) | **ALWAYS - before ANY operation** |
| **`.claude/standards/ENGINEERING_STANDARDS.md`** | Code quality standards and patterns | **ALWAYS - before writing code** |

**If you have not read these files in this session, READ THEM NOW using the Read tool.**

This is not optional. Violations of these standards are critical errors that waste time and break workflows.

### Key Rules Summary (from `.claude/standards/`)

1. **NEVER push to main** - Always use feature branches and pull requests
2. **NEVER modify system Python** - Always use virtual environments
3. **ALWAYS run tests** - `pytest tests/ -v` before every commit
4. **ALWAYS use atomic commits** - One logical change per commit
5. **ALWAYS update docs** - Documentation changes go with code changes

---

## Before You Begin

**Read these files IN ORDER before performing any operations:**

1. **`.claude/standards/CLAUDE_CODE_RULES.md`** - Non-negotiable requirements
2. **`.claude/standards/ENGINEERING_STANDARDS.md`** - Coding standards and best practices
3. **`.claude/knowledge/README.md`** - Knowledge base index
4. **`.claude/WHEN_TO_READ.md`** - Quick reference for when to read what

## Critical Rules

### NEVER Push to Main Branch

- ALWAYS create feature branch: `git checkout -b feature/name`
- ALWAYS use pull requests
- Check current branch before pushing: `git branch --show-current`

### NEVER Modify System Python

- ALWAYS use virtual environments: `python3 -m venv .venv && source .venv/bin/activate`
- Check venv active: `which python` (must show `.venv/bin/python`)
- NEVER use: `pip install` without venv, `--user` flag, `sudo pip`

### ALWAYS Run Full Test Suite

- Before every commit: `uv run pytest tests/ -v` (FULL suite, not subsets)
- Verify coverage meets threshold (check actual percentage in output, not just exit code)
- Run ALL quality checks: `uvx ruff check . && uvx ruff format . && uvx ty check src/`
- Fix failing tests immediately
- Don't commit if tests fail
- NEVER claim "tests pass" or "PR ready" based on partial test runs

### ALWAYS Verify Branch

- Check branch: `git branch --show-current`
- If on main: Create feature branch immediately

## Quick Reference

### PR Workflow
See: `.claude/knowledge/git/pull-request-workflow.md`

```bash
git checkout -b feature/my-feature
# Make changes (commit after EACH logical unit)
pytest tests/ -v
git add .
git commit -m "feat: description"  # ONE change per commit!
git push -u origin feature/my-feature
gh pr create
```

### Atomic Commits
See: `.claude/knowledge/git/atomic-commits.md`

```bash
# The "AND" Test: If message uses "and", split into multiple commits
# BAD: git commit -m "feat: add form and fix validation"
# GOOD:
git commit -m "feat: add login form"
git commit -m "fix: resolve validation error"
```

### Python Setup
See: `.claude/knowledge/python/virtual-environments.md`

```bash
# Using uv (recommended)
uv sync --all-extras
lefthook install  # Install git hooks

# Or traditional venv
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
lefthook install
```

Or use `just setup` to do all of the above in one command.

### Testing
See: `.claude/knowledge/testing/pytest-basics.md`

```bash
uv run pytest tests/ -v
uv run pytest tests/ --cov=src
uv run pytest -m "not e2e"  # Skip slow tests
```

### Code Quality
See: `.claude/knowledge/automation/pr-iteration.md`

```bash
just check  # Run all checks (lint, format, typecheck, test)
# Or manually:
uvx ruff check --fix .
uvx ruff format .
uvx ty check src/
uv run pytest tests/
```

### Model Configuration
See: `.claude/knowledge/claude-code/model-configuration.md`

**Default**: Opus (all operations)

**Override options**:
- Session: `/model sonnet` (temporary)
- Environment: `export ANTHROPIC_MODEL="sonnet"` in `.envrc` (persistent)
- Team settings: Edit `.claude/settings.json` (affects all sessions)

## Pre-Operation Checklist

**Before ANY operation, verify:**

- [ ] Read project `.claude/CLAUDE.md` (this file)
- [ ] Check venv active: `which python` → `.venv/bin/python`
- [ ] Check branch: `git branch --show-current` → NOT main
- [ ] Read files before editing (use Read tool)
- [ ] Plan atomic commits (one logical change per commit)

## Documentation

- **Engineering Standards**: `.claude/standards/ENGINEERING_STANDARDS.md`
- **Critical Rules**: `.claude/standards/CLAUDE_CODE_RULES.md`
- **Knowledge Base**: `.claude/knowledge/` (tactical tips and patterns)
- **When to Read What**: `.claude/WHEN_TO_READ.md` (documentation reading guide)

## Project-Specific Rules

*This file may be customized per project. Check if project has additional rules below this line.*

---

## Feature Implementation Workflow

**For any non-trivial feature or change, use this pipeline:**

1. **Brainstorm first** → `superpowers:brainstorming`
   - Explore options with multiple-choice questions
   - Make decisions before writing code
   - End with a validated design

2. **Write a plan** → `superpowers:writing-plans`
   - Break into bite-sized tasks (2-5 min each)
   - Include exact files, code, commands, commits
   - Save to `docs/plans/YYYY-MM-DD-<topic>.md`

3. **Execute with subagents** → `superpowers:subagent-driven-development`
   - Fresh subagent per task (no context pollution)
   - Spec compliance review after each task
   - Code quality review after each task
   - Fix loops until approved

**IMPORTANT:** After writing a plan, ALWAYS ask:

> "Plan complete. Two execution options:
> 1. **Subagent-Driven** - Fresh subagent per task with two-stage review
> 2. **Direct Implementation** - I implement directly
>
> Which approach?"

Do NOT skip this choice and start coding directly. The subagent approach with reviews catches issues early and produces higher quality results.

**To explicitly request this workflow:**
- "Use subagent-driven development to implement this"
- "Execute with the full pipeline: brainstorm → plan → subagent execution"
