seek: Instructions file for Claude Code

seek — project guide for AI assistants

This file is read at the start of every Claude Code session in this repo. It mirrors AGENTS.md, which seek itself auto-loads at startup. The two files are related but allowed to diverge where each agent's tooling differs (see AGENTS.md vs CLAUDE.md).

Treat the instructions below as mandatory project conventions.

Pitfall recording (load-bearing — read this)

When you fix a non-obvious bug, discover an undocumented API constraint, or find a surprising piece of behaviour:

1. Append an entry to docs/pitfalls.md using the template at the top of that file. Categorise it (TUI / DeepSeek API / Go / Tooling / etc.); keep it terse — symptom, root cause, fix, lesson, refs.
2. Add a Pitfall: <one-line summary> trailer to the commit message. Multiple pitfalls in one commit = multiple trailers.
3. The trailer is what scripts/extract-pitfalls.sh reads — it's the redundant signal so docs/pitfalls.md can be regenerated if it ever falls out of sync.

What counts as "non-obvious":

• A behaviour that surprised you (or the user) for more than a minute.
• An API contract that isn't documented in the obvious spot.
• A workaround for a tooling / classifier / sandbox limitation.
• A design constraint that, if forgotten, would be re-discovered painfully.

What does not count:

• Routine typos, missing imports, version bumps, refactors.
• Anything obvious from reading the code or running go vet.

If you're not sure: log it — but only for pitfalls produced by the change at hand; if you stumble on something unrelated mid-task, name it in your final message instead of expanding the diff, and let the user decide whether it deserves an entry. Cheap to add, expensive to recover from memory months later.

Architecture (non-negotiable)

• DeepSeek-first, two-tier providers. pkg/deepseek is a first-class client with DeepSeek-specific fields (cache metadata, FIM endpoint, reasoner content). pkg/llm is a thin generic interface for second-tier providers (Anthropic / OpenAI / Gemini — landing in M6).
• pkg/deepseek must not import pkg/llm (CI lint enforces this — see .github/workflows/ci.yml). The whole point of the split is that DeepSeek-specific optimisations don't get lowered into a generic interface.
• Skill subsystem (v2): read-only loader in internal/skill (Anthropic Agent Skills layout: <dir>/SKILL.md + frontmatter); install/uninstall/update in internal/skillmgr; call-stats JSONL in internal/skillstats; shared CLI/TUI dispatcher in internal/skillcli. Loader is the only path that runs at startup; everything else is on-demand. Never add filesystem writes under ~/.seek/skills/ outside internal/skillmgr and internal/skillstats — those are the only two packages allowed to mutate user-level skill state.
• Plan-mode subsystem (v2 + v2.x): confirmation-gated workflow analyze → propose → execute → adjust → report. Driven by the propose tool (internal/tools/propose/) and progress-tracked by the plan tool (internal/tools/plan/). Substate state machine lives in permission.Policy (Mode / preApproved flag) + agent mode reminder + TUI status bar; transcript event-sourcing reconstructs state on seek -resume (see plan/reconstruct.go). Plan-approval artifacts (write-once markdown snapshots) land in ~/.seek/projects/<id>/plans/ via plan/artifact.go. Full design + status table in docs/prd/feature-plan-mode.md.
• i18n (view layer only): catalogue in internal/i18n (i18n.T; every key goes in ALL catalogues — parity-tested). Human-facing prose only; LLM-visible strings and the status bar stay English (prefix-cache bytes + width oracle). Language resolves once per session; /lang is the only runtime swap. Design + scope: docs/prd/feature-i18n.md.
• See docs/prd/ for the full PRD series: v0 initial, v1 Memory, v2 Skill lifecycle, plus standalone feature PRDs (feature-plan-mode.md, feature-webfetch.md, feature-permission-refactor.md, feature-active-memory.md, feature-mcp-client.md, …).