lingtai-dev-guide

LingTai Developer Guide

The cross-repository developer router for LingTai. The root stays short on purpose; detailed procedures live under reference/<topic>/.

Repository-local developer guidance takes precedence

Before using this guide, look for developer guidance maintained by the current repository and read it first. When it exists, follow it for repository-specific rules; it takes precedence over this global guide. Use this guide afterward — or when the local guide routes here — to select the deeper cross-repository topic you need, then read that nested reference before touching code. Do not substitute generic procedures here for local guidance, or restate local rules from memory.

Non-negotiable rules

• Progressive disclosure: router → nested reference → anatomy skill → code + tests. Never jump from memory straight to edits.
• Code is truth: reference files route and summarize; cited source files, tests, and ANATOMY.md files are authoritative.
• Anatomy travels with code: if you move/rename/split/delete code cited by an ANATOMY.md, update the anatomy in the same commit, following the ANATOMY frontmatter contract below.
• Explicit human authorization gates: do not open/merge PRs, push commits, file issues, close/delete resources, or change config unless the human gave an imperative authorization for that side effect.
• Human-facing deliverables prefer HTML: substantial plans, audits, release notes, and PR-readiness reports should be standalone HTML unless waived.
• Release/install docs rule: LingTai runtime is normally managed by the TUI-created project venv; do not present bare pip install/upgrade lingtai as the standard user path. Manual pip/venv commands are for developer, diagnostic, or verification contexts only.
• Patch-to-self ownership rule: a merged PR or rebuilt checkout is not automatically live in the agent. The update/build owner must identify the actual runtime interpreter, imported source/package, HEAD/version, and intended selectors, then hand off the cutover target evidence. Kernel system-manual → reference/refresh-precheck/SKILL.md alone owns the refresh transaction and targeted receipt. Load reference/runtime-self-check/SKILL.md only for the relevant provenance assertion or a suspected mismatch; an ordinary same-runtime reload does not invoke its deep diagnostic library.
• Skill-size/progressive-disclosure rule: when writing or updating skills, treat read/context limits as a reason to keep the router lean and link onward, not as a reason to paste large content into SKILL.md. Put dense material in related/nested reference files and link to skills-manual for current authoring mechanics and limit-aware structure.
• Launch-session / PYTHONPATH hygiene rule: never launch the TUI or an agent from a shell session that exports PYTHONPATH. A leftover PYTHONPATH pointing at another project's scratch/worktree/temp repo src shadows the venv's own lingtai import, and because the refresh watcher copies os.environ verbatim, the pollution survives refresh — a plain refresh re-inherits it. Debug sessions that export PYTHONPATH=... for one experiment silently infect every agent they launch. See reference/gotchas/SKILL.md ("PYTHONPATH pollution") and reference/runtime-self-check/SKILL.md §1 for the probe and §8 for the clean-relaunch recipe.