kluris: Instructions file for Claude Code

CLAUDE.md

What This Is

Kluris turns AI agents into team subject matter experts by giving them shared, human-curated knowledge stored in git-backed brains.

Kluris = the tool. A brain = the git repo it creates.

Knowledge base

Read and write to the ngvoicu-sme brain through kluris (never edit brain files by hand). Use the /kluris-ngvoicu-sme skill — search, learn, remember, create.

Topics relevant to this repo: kluris-cli overview, architecture, multi-brain resolver, agent skills, kluris-pack, wake-up protocol, testing, CI/CD, deprecation.

Build & Test

source .venv/bin/activate        # or: pipx install -e .
pip install -e ".[dev]"          # dev install with pytest
pytest tests/ -v                 # run all tests (979 tests)
pytest tests/ --cov=kluris -q    # with coverage (90%+)
pytest tests/test_create.py -v   # single test file

Architecture

src/kluris/
  cli.py              # Click CLI -- all 13 commands in one file (incl. search, wake-up, pack, register, companion)
  core/
    config.py          # Pydantic models (GlobalConfig, BrainConfig, BrainEntry)
    brain.py           # BRAIN_TYPES, scaffold_brain(), validate_brain_name()
    maps.py            # generate_brain_md(), generate_map_md() -- auto-generated files
    frontmatter.py     # read_frontmatter(), write_frontmatter(),
                       # update_frontmatter(path, patch, *, preloaded=(meta, body)?)
    linker.py          # validate_synapses(), validate_bidirectional(), detect_orphans(),
                       # detect_deprecation_issues(), check_frontmatter() with type validation
    search.py          # _collect_searchable(), _score_hit(), _matched_fields(),
                       # _extract_snippet(), search_brain() -- backs `kluris search`
    mri.py             # build_graph(), generate_mri_html() -- standalone HTML viz
    git.py             # git_init(), git_add(), git_commit(), git_log(),
                       # git_log_file_dates() batch helper (one subprocess replaces 2N)
    agents.py          # AGENT_REGISTRY (9 agents), per-brain SKILL.md renderer
                       # (always kluris-<name>, even for one brain);
                       # brain_path emitted in POSIX form (C:/ on Windows) for bash