Contributing to LingTai

Contributing to LingTai

Nested lingtai-dev-guide reference. Read this after the top-level router sends you here.

General principles

1. Filesystem-only IPC. TUI, portal, and kernel communicate exclusively through files. Need cross-process communication? Write a file and let the other side poll.
2. Anatomy updates are part of the code change. If your change moves, renames, splits, merges, or deletes anything cited by an ANATOMY.md, update the anatomy in the same commit (see "Anatomy maintenance" below).
3. Three-locale rule. A new i18n key means updating en.json, zh.json, and wen.json in both tui/i18n/ and (where applicable) portal/i18n/. Missing translations render as the raw key — they don't fall back.
4. Binary naming. The TUI binary is lingtai-tui, never lingtai. lingtai is the Python agent CLI inside the runtime venv.
5. Every non-trivial PR gets a self-contained HTML explainer, local-only by default. Requirements, naming, sections, the commit-vs-local rule, and the waiver exception live in reference/pr-review-deliverables/SKILL.md §3 — follow it rather than a summary here.
6. Prefer one honest sandbox acceptance when it exercises the real end-to-end path. Keep only minimal syntax/smoke checks for obvious breakage; open the reviewable PR promptly and continue broader validation after the PR when needed, rather than building a broad pytest or synthetic matrix.
7. Every test must earn its maintenance cost by protecting a distinct failure invariant. Inventory existing coverage before adding cases. When one mechanism needs multiple inputs, prefer table-driven or parameterized cases and shared setup over one pytest per narrative example. Do not inflate a PR with exhaustive assertion prose, and do not delete non-overlapping old tests merely to make the diff smaller.

Orchestrator + daemons (how the work happens)

The operating discipline for any non-trivial LingTai contribution — TUI, portal, kernel, addons, or skills.

1. Clarify and restate the contract

Before dispatching, restate the task: what changes, what does not, what "done" looks like, what is out of scope. Ask if the request is ambiguous. A daemon run against a fuzzy brief delivers a fuzzy diff, and you pay for it in review time.

2. Issue → worktree/branch → PR → merge

Non-trivial work flows through this loop — no exceptions for "small" fixes that turn out to be non-small:

1. Issue. Open or pick a GitHub issue naming the problem. If none exists, write one — it is the durable record of the contract.
2. Worktree + branch. Isolated git worktree off origin/main on a topic branch (fix/..., feat/..., docs/..., chore/...). Never edit the main checkout; never share a worktree between parallel daemons.
3. PR. Push and open against Lingtai-AI/<repo>. The body cites the issue, summarizes the change, lists validation steps.
4. Merge. After review, merge via the GitHub UI or gh pr merge, then delete the branch and clean up the worktree (see "Worktree hygiene").

3. Decompose into daemon-sized tasks

Orchestrators plan, dispatch, and review; they do not hand-code. Code reading, modification, testing, refactoring, PR preparation, batch scanning, and mechanical validation belong to the daemon backends — Claude Code daemons for exploratory reading, multi-file edits, skill/doc work, and PR composition; Codex daemons for tightly-scoped diffs, deterministic refactors, and mechanical validation.

Every dispatched daemon gets four things:

• A scoped brief — what to change, what to leave alone, what "done" means, absolute paths to source-of-truth files.
• Its own worktree and branch — parallelism is safe only when worktrees are disjoint.
• Tests or validation steps — go test ./..., python -m pytest, frontmatter parse, git diff --check, a grep for new headings; or an explicit "none applicable."