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.

ANATOMY frontmatter contract

New or materially updated ANATOMY.md files should start with YAML frontmatter:

---
related_files:
  - path/from/repo/root.ext
  - path/to/neighbor/ANATOMY.md
maintenance: |
  Keep related_files as repo-relative paths to real files. Include neighboring
  ANATOMY.md files so the anatomy graph stays connected rather than isolated;
  anatomy links must be bidirectional. If you create a new ANATOMY.md, copy this
  maintenance field. If you notice drift between this anatomy and the code,
  report it. See lingtai-dev-guide for details.
---

Rules:

• related_files uses repo-relative paths only; every entry must be a real file.
• Include the files the anatomy explains plus neighboring/parent/child ANATOMY.md files. Do not build a complete graph — choose meaningful links — but an isolated ANATOMY.md is invalid, and anatomy-to-anatomy links must be bidirectional: if A lists B, B should list A.
• maintenance carries the recursive instruction: copy it into new anatomy files and report drift when anatomy and code no longer match.

Nested reference catalog

lingtai-dev-guide owns these nested references. They are parent-owned drill-down files, not standalone top-level skills.

- name: dev-guide-architecture
  location: reference/architecture/SKILL.md
  description: |
    Project shape, repos, IPC boundaries, and runtime state layout.
- name: dev-guide-setup
  location: reference/setup/SKILL.md
  description: |
    Local dev environment for the Go TUI/portal repo, Python kernel, and MCP addons.
- name: dev-guide-contributing
  location: reference/contributing/SKILL.md
  description: |
    Contribution workflow, daemon decomposition, build/test commands, skill
    changes, anatomy maintenance, and worktree hygiene with exact-object
    approval gates.
- name: dev-guide-gotchas
  location: reference/gotchas/SKILL.md
  description: |
    Known footguns: venv assumptions, migrations, packaging, state files, i18n.
- name: dev-guide-debug-troubleshoot
  location: reference/debug-troubleshoot/SKILL.md
  description: |
    Diagnosing stuck, errored, quiet, or misbehaving LingTai networks.
- name: dev-guide-security-audit
  location: reference/security-audit/SKILL.md
  description: |
    Read-only audits of secrets, permissions, MCP config, channels, and data
    exposure, with severity classification and safe reporting.
- name: dev-guide-runtime-self-check
  location: reference/runtime-self-check/SKILL.md
  description: |
    Deep, trigger-gated provenance and lifecycle diagnosis for a source/venv/
    interpreter or TUI-binary cutover, changed or failing MCP source, or a
    suspected mismatch. Ordinary reload sequencing belongs to kernel
    `system-manual` → `reference/refresh-precheck/SKILL.md`.
- name: dev-guide-pr-review-deliverables
  location: reference/pr-review-deliverables/SKILL.md
  description: |
    PR readiness gates, independent review passes, the self-contained local HTML
    explainer, PR body hygiene, and maintainer authorization boundaries.
- name: dev-guide-skill-stewardship
  location: reference/skill-stewardship/SKILL.md
  description: |
    Turning experience into durable skills: when to write one, router-vs-nested
    structure, distillation (归一), de-privatization, a pre-publish benchmark,
    shared-library grooming, and PR-ready cleanup. Cross-links skills-manual.
- name: dev-guide-repo-watch
  location: reference/repo-watch/SKILL.md
  description: |
    Read-only sweep of the Lingtai-AI org for open issues/PRs and recent
    activity, plus non-self monitoring and stateful alerting.
- name: dev-guide-cache-hit-rate
  location: reference/cache-hit-rate/SKILL.md
  description: |
    Recent prompt-cache hit rate from token ledgers over rolling windows
    (1h/5h/1d/3d): ledger fields, the formula, the daemon double-count hazard,
    and the bundled read-only stdlib script.

Routing table

Related skills to load instead or next

Orientation snapshot

Common routing examples

Multi-hop routes the table above doesn't spell out:

• "Change a TUI screen" → reference/contributing/SKILL.md → lingtai-tui-anatomy → relevant Go files → focused go test.
• "Update an ANATOMY.md" → repo-specific anatomy skill → apply the ANATOMY frontmatter contract above, and report stale citations, dead paths, or claims that no longer match the code.
• "Add a capability or inspect runtime behavior" → lingtai-kernel-anatomy → kernel anatomy/code → kernel tests.
• "This broad dev task needs triage" → the read-only portfolio sweep in reference/contributing/SKILL.md, then ask for authorization before mutating GitHub state.
• "Local worktrees are piling up" → "Worktree hygiene" in reference/contributing/SKILL.md: inventory read-only, propose exact objects, remove only after the human or owning maintainer approves them.

Now read the nested reference that matches the task, then verify against current repo state before acting.