markitect-main/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Custodian State Hub Integration

This project is tracked as the markitect domain in the Custodian State Hub. Hub topic ID: 5571d954-0d30-4950-980d-7bcaaad8e3e2

Session start: Call get_domain_summary("markitect") via the state-hub MCP tool. If the hub is not reachable: cd ~/the-custodian/state-hub && make api

Session end: Call add_progress_event() with topic_id above, a summary, and event_type (note / milestone / blocker).

Available state-hub MCP tools: get_state_summary, get_domain_summary, add_progress_event, create_workstream, create_task, update_task_status, record_decision, resolve_decision.

If the hub API is unavailable, use curl against http://127.0.0.1:8000/docs.

---

Development Commands

All commands assume the markitect-venv virtual environment is active (source ~/.venvs/markitect-venv/bin/activate or equivalent). The package is installed in editable mode.

# Run the core test suite
pytest

# Run a single test file
pytest tests/test_issue_17_batch_processing.py

# Run tests by marker
pytest -m unit
pytest -m "not slow"

# Run with coverage
pytest --cov=markitect

# Run only fast unit tests (TDD inner loop)
pytest tests/unit/

# CLI entry point
markitect --help

# Infospace subcommands (primary active development area)
markitect infospace --help
markitect infospace eval-summary --update-metrics

# LLM helper commands
markitect llm-helper "<question>"
markitect llm-catalog
markitect llm-check
markitect llm-default
markitect llm-preference

# Install / reinstall in dev mode
pip install -e ".[analysis]"

Architecture

MarkiTect is a CLI-driven markdown engine that treats documents as structured, queryable information spaces. Entry point: markitect/cli.py → main() (Click group). All subcommand groups are registered at the bottom of cli.py.

Core Modules (markitect/)

Module	Purpose
spaces/	InformationSpace model — composability, events, history, transclusion, rendering, sync
prompts/	Prompt resolver, compiler, execution engine, quality gates, dependency graph, traceability
llm/	LLM adapter layer — 4 text providers + embedding adapter; 7-layer config resolution
infospace/	Infospace lifecycle — init, entity parsing, evaluation, composition, graph export
analysis/	Graph analysis (networkx) and FCA (Formal Concept Analysis, pure Python)
schema*/	Schema generation, validation, naming, refinement, metaschema
core/	Foundational parser, AST, serializer, workspace

LLM Configuration (markitect/llm/)

Resolution order (highest → lowest priority):

1. CLI flags (--provider, --model)
2. MARKITECT_HELPER_MODEL env var (model only)
3. User preference ([llm.preference] in ~/.config/markitect/config.toml)
4. Directory preference ([llm.preference] in .markitect.toml)
5. Directory default ([llm.default] in .markitect.toml)
6. User default ([llm.default] in ~/.config/markitect/config.toml)
7. Hardcoded fallback: gemini/gemini-2.5-flash

Canonical models: markitect/llm/models.py (RunConfig, LLMResponse) and markitect/llm/adapter.py (LLMAdapter). These are mirrored in the standalone /home/worsch/llm-connect/ package (llm_connect), which is installed as a local path dependency. markitect/prompts/execution/{models,llm_adapter}.py are re-export shims for backward compatibility.

Gotcha: The OPENROUTER_API_KEY env var may hold a stale key — unset OPENROUTER_API_KEY before running LLM commands if you get auth errors. claude-code provider fails inside Claude Code sessions (nested session restriction).

Infospace (markitect/infospace/)

An infospace is a directory-based collection of typed entities governed by an infospace.yaml config. Key files:

• config.py — config loading, find_infospace_config(), DisciplineBinding
• entity_parser.py — parse entity markdown files from output/entities/<slug>.md
• evaluation.py / evaluation_io.py — per-entity LLM evaluation (5 dimensions)
• state.py — build_state() aggregates entity + evaluation state
• history.py / checks/ — viability tracking and collection-level checks

Slugs use underscores (e.g., accumulation_of_stock). Active example: examples/infospace-with-history/ (988 entities).

Layered Architecture

The project has a partially-implemented layered architecture separate from markitect/:

• domain/ — domain models (issues, projects)
• infrastructure/ — config, repositories, logging, connection management
• application/ — application layer (mostly empty)
• capabilities/ — pluggable capability packages (issue-facade, release-management, testdrive-jsui, markitect-utils, markitect-content, kaizen-agentic)

Tests

Tests live in tests/. Many test files are named test_issue_NNN_*.py (TDD by issue). Layered tests follow test_l{N}_*.py naming. The tests/unit/ subtree has the cleanest structure and covers prompts/, spaces/, llm/, infospace/, analysis/.

Pytest config is in pytest.ini. Relevant markers: unit, integration, e2e, slow, performance.

Active Roadmap Files

• roadmap/infospace-tooling/PLAN.md — main infospace roadmap (S1 ✅ S2 ✅ S3 nearly done)
• roadmap/infospace-s3-closeout/PLAN.md — S3 close-out tasks (C.1–C.8)
• roadmap/llm-shared-library/PLAN.md — llm-connect extraction (S1+S2 done, S3 pending)