docs: add CLAUDE.md, contributing guide, and dev documentation

.github/workflows/ci.yml

@@ -47,6 +47,8 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Run tests
+        env:
+          RUN_INTEGRATION_TESTS: "1"
         run: |
           uv run pytest tests/ \
             -n auto \

CLAUDE.md

@@ -0,0 +1,80 @@
+# CLAUDE.md — AI Company
+
+## Project
+
+- **What**: Framework for orchestrating autonomous AI agents within a virtual company structure
+- **Python**: 3.14+ (PEP 649 native lazy annotations)
+- **License**: BUSL-1.1 (converts to Apache 2.0 on 2030-02-27)
+- **Layout**: `src/ai_company/` (src layout), `tests/` (unit/integration/e2e)
+- **Design**: [DESIGN_SPEC.md](DESIGN_SPEC.md) (full high-level spec)
+
+## Quick Commands
+
+```bash
+uv sync                                    # install all deps (dev + test)
+uv run ruff check src/ tests/              # lint
+uv run ruff check src/ tests/ --fix        # lint + auto-fix
+uv run ruff format src/ tests/             # format
+uv run mypy src/                           # type-check (strict)
+uv run pytest tests/ -m unit               # unit tests only
+uv run pytest tests/ -m integration        # integration tests only
+uv run pytest tests/ -n auto --cov=ai_company --cov-fail-under=80  # full suite + coverage
+uv run pre-commit run --all-files          # all pre-commit hooks
+```
+
+## Package Structure
+
+```text
+src/ai_company/
+  api/            # FastAPI REST + WebSocket routes
+  budget/         # Per-agent cost tracking and spending controls
+  cli/            # Typer CLI commands
+  communication/  # Inter-agent message bus and channels
+  config/         # YAML company config loading and validation
+  core/           # Shared domain models and base classes
+  engine/         # Agent execution engine and task lifecycle
+  memory/         # Persistent agent memory (Mem0 adapter)
+  providers/      # LLM provider abstraction (LiteLLM adapter)
+  security/       # SecOps agent, approval gates, sandboxing
+  templates/      # Pre-built company templates and builder
+  tools/          # Tool registry, MCP integration, role-based access
+```
+
+## Code Conventions
+
+- **No `from __future__ import annotations`** — Python 3.14 has PEP 649
+- **Type hints**: all public functions, mypy strict mode
+- **Docstrings**: Google style, required on public classes/functions (enforced by ruff D rules)
+- **Immutability**: create new objects, never mutate existing ones
+- **Models**: Pydantic v2 (`BaseModel`, `model_validator`, `ConfigDict`)
+- **Line length**: 88 characters (ruff)
+- **Functions**: < 50 lines, files < 800 lines
+- **Errors**: handle explicitly, never silently swallow
+- **Validate**: at system boundaries (user input, external APIs, config files)
+
+## Testing
+
+- **Markers**: `@pytest.mark.unit`, `@pytest.mark.integration`, `@pytest.mark.e2e`, `@pytest.mark.slow`
+- **Coverage**: 80% minimum (enforced in CI)
+- **Async**: `asyncio_mode = "auto"` — no manual `@pytest.mark.asyncio` needed
+- **Timeout**: 30 seconds per test
+- **Parallelism**: `pytest-xdist` via `-n auto`
+
+## Git
+
+- **Commits**: `<type>: <description>` — types: feat, fix, refactor, docs, test, chore, perf, ci
+- **Enforced by**: commitizen (commit-msg hook)
+- **Branches**: `<type>/<slug>` from main
+- **Pre-commit hooks**: trailing-whitespace, end-of-file-fixer, check-yaml, check-toml, check-json, check-merge-conflict, check-added-large-files, no-commit-to-branch (main), ruff check+format, gitleaks
+
+## CI
+
+- **Jobs**: lint (ruff) + type-check (mypy) + test (pytest + coverage) run in parallel → ci-pass (gate)
+- **Matrix**: Python 3.14
+- **Dependabot**: daily uv + github-actions updates, auto-merge for patch/minor
+
+## Dependencies
+
+- **Pinned**: all versions use `==` in `pyproject.toml`
+- **Groups**: `test` (pytest + plugins), `dev` (includes test + ruff, mypy, pre-commit, commitizen, pydantic)
+- **Install**: `uv sync` installs everything (dev group is default)

CONTRIBUTING.md

@@ -0,0 +1,142 @@
+# Contributing to AI Company
+
+## Quick Start
+
+```bash
+git clone https://github.com/Aureliolo/ai-company.git
+cd ai-company
+uv sync
+```
+
+For the full setup walkthrough (prerequisites, IDE config, etc.), see [docs/getting_started.md](docs/getting_started.md).
+
+## Branching Strategy
+
+Branch from `main`. Use the naming convention:
+
+```text
+<type>/<slug>
+```
+
+Examples: `feat/agent-engine`, `fix/config-validation`, `docs/api-reference`
+
+Types match commit types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`.
+
+## Making Changes
+
+1. Create a feature branch: `git checkout -b feat/my-feature main`
+2. Install hooks (first time only): `uv run pre-commit install`
+3. Make your changes
+4. Run quality checks (see below)
+5. Commit using conventional commit format
+6. Push and open a pull request
+
+## Commit Conventions
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/) enforced by commitizen.
+
+```text
+<type>: <description>
+
+<optional body>
+```
+
+### Types
+
+| Type | When to use |
+|------|-------------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `refactor` | Code restructuring (no behavior change) |
+| `docs` | Documentation only |
+| `test` | Adding or updating tests |
+| `chore` | Maintenance, tooling, config |
+| `perf` | Performance improvement |
+| `ci` | CI/CD changes |
+
+### Examples
+
+```text
+feat: add YAML config loader with schema validation
+fix: prevent division by zero in budget calculator
+test: add integration tests for message bus
+docs: update API reference for provider layer
+```
+
+Keep the description lowercase, imperative, and under 72 characters. The optional body can provide additional context.
+
+## Code Quality Checks
+
+Run these before pushing:
+
+```bash
+uv run ruff check src/ tests/              # lint
+uv run ruff format --check src/ tests/     # format check
+uv run mypy src/                           # type check
+```
+
+Auto-fix lint and formatting issues:
+
+```bash
+uv run ruff check src/ tests/ --fix
+uv run ruff format src/ tests/
+```
+
+## Running Tests
+
+```bash
+uv run pytest tests/ -m unit               # unit tests (fast)
+uv run pytest tests/ -m integration        # integration tests
+uv run pytest tests/ -m e2e                # end-to-end tests
+uv run pytest tests/ -n auto --cov=ai_company --cov-fail-under=80  # full suite + coverage
+```
+
+All tests must pass and coverage must remain at or above 80%.
+
+## Pre-commit Hooks
+
+Hooks run automatically on `git commit`. If a hook fails:
+
+1. Review the output — most hooks (ruff, trailing whitespace) auto-fix the issue
+2. Stage the auto-fixed files: `git add .`
+3. Commit again
+
+To run all hooks manually:
+
+```bash
+uv run pre-commit run --all-files
+```
+
+See [docs/getting_started.md](docs/getting_started.md) for the full list of hooks and what each one does.
+
+## Code Style
+
+Code conventions (type hints, docstrings, immutability, line length, etc.) are documented in [CLAUDE.md](CLAUDE.md). Both human contributors and AI assistants follow the same rules.
+
+## Pull Request Process
+
+1. Ensure all quality checks pass locally (lint, type-check, tests)
+2. Push your branch: `git push -u origin feat/my-feature`
+3. Open a PR against `main`
+4. Fill in the PR description: what changed, why, and how to test
+5. CI must pass (lint, type-check, test with coverage)
+6. Address review feedback
+7. Squash-merge when approved
+
+## Project Structure
+
+```text
+src/ai_company/       # Main package
+  api/  budget/  cli/  communication/  config/  core/
+  engine/  memory/  providers/  security/  templates/  tools/
+tests/
+  unit/  integration/  e2e/
+docs/                 # Developer documentation
+.github/              # CI, dependabot, actions
+```
+
+See [docs/getting_started.md](docs/getting_started.md) for descriptions of each sub-package.
+
+## License
+
+This project is licensed under [BUSL-1.1](LICENSE). By contributing, you agree that your contributions will be licensed under the same terms.

README.md

@@ -35,6 +35,19 @@ AI Company lets you spin up a virtual organization staffed entirely by AI agents
 - **Vue 3** for web dashboard (planned)
 - **SQLite** → PostgreSQL for data persistence (planned)
 
+## Getting Started
+
+```bash
+git clone https://github.com/Aureliolo/ai-company.git
+cd ai-company
+uv sync
+```
+
+See [docs/getting_started.md](docs/getting_started.md) for prerequisites, IDE setup, and the full walkthrough.
+
 ## Documentation
 
+- [Getting Started](docs/getting_started.md) - Setup and installation guide
+- [Contributing](CONTRIBUTING.md) - Branch, commit, and PR workflow
+- [CLAUDE.md](CLAUDE.md) - Code conventions and AI assistant reference
 - [Design Specification](DESIGN_SPEC.md) - Full high-level design