ait: Instructions file for Claude Code

CLAUDE.md

This file gives Claude Code the project-specific context it needs to work on this repository safely and consistently. It mirrors the rules in AGENT.md but adds the technical details Claude Code needs (stack, commands, layout, entry points).

When AGENT.md and this file disagree, treat them as equally authoritative and ask before diverging.

Project Overview

ait is an AI-agent-native VCS layer that sits on top of Git. It adds structured intent tracking, isolated attempts, queryable execution history, and durable linkage between attempts and Git commits. It is not a replacement for Git.

Canonical specs live in docs/:

• docs/ai-vcs-mvp-spec.md — v1 spec (frozen surface)
• docs/implementation-notes.md — non-blocking clarifications and known limits
• docs/protocol-appendix.md — daemon protocol details
• docs/implementation-plan.md — milestones, acceptance criteria, breakdown
• docs/parallel-development.md — parallel work coordination

Treat the spec as the source of truth. If implementation and spec disagree, that is a bug to be reviewed, not a silent divergence.

Tech Stack

• Python >=3.14 (see pyproject.toml)
• SQLite via stdlib sqlite3
• stdlib unittest for tests
• stdlib argparse, socket, subprocess — no runtime dependencies

The project must stay dependency-free unless a new dependency is explicitly approved and documented.

Repository Layout

src/ait/
  __init__.py
  cli.py                # argparse entry point (`ait ...`)
  app.py                # high-level operations (init/intent/attempt/show/...)
  config.py             # .ait dir bootstrap, install_nonce, local config
  repo.py               # git repo root resolution, repo_id derivation
  ids.py                # ULID generation
  hooks.py              # post-rewrite hook installer
  workspace.py          # worktree provisioning, commit helpers, ref updates
  daemon.py             # daemon process lifecycle (start/stop/serve)
  daemon_transport.py   # NDJSON unix socket transport
  protocol.py           # event envelope + payload schemas and validation
  events.py             # event handlers, dedupe, reaper, lifecycle updates
  verifier.py           # succeeded/promoted/failed determination
  query.py              # DSL parser, whitelisted fields, SQL lowering, blame
  reconcile.py          # post-rewrite reconciliation
  db/
    __init__.py         # re-exports
    core.py             # connect_db, run_migrations, meta table helpers
    schema.py           # migrations tuple, SCHEMA_VERSION
    repositories.py     # typed insert/get/list helpers per table
tests/
  test_*.py             # stdlib unittest
docs/                   # see above
AGENT.md                # base working rules
CLAUDE.md               # this file
pyproject.toml