@andyqiu/teamkit 0.1.1

package/context-templates/git-instructions.md

@@ -0,0 +1,69 @@
+<!--
+teamkit Git Agent 行为约束模板。
+- 由 install.sh 在 install 时同步进项目 AGENTS.md 的 <!-- teamkit-git:start/end --> 块
+- 修改本文件后需重新 install 才能生效
+- 覆盖 PRD v0.2 §4.4 R13/R14
+-->
+
+# Git Agent 行为约束（teamkit-git）
+
+## Git 触发词列表
+
+当用户消息包含以下任意触发词时，主 agent **必须**通过 `Task tool` 调用 `teamkit-git` subagent：
+
+**中文触发词：**
+> 提交 / 推送 / 上传 / 推上去 / 推过去 / 拉取 / 拉一下 / 同步 / 新分支 / 建分支 / 创建分支 / 切分支 / 切换分支 / 分支 / 合并 / 差异 / 改动了什么 / 变更 / 状态 / 暂存 / 回退 / 撤销 / 打标签 / 版本
+
+**英文触发词：**
+> commit / push / pull / sync / branch / merge / git status / git add / git diff / git log / stash / checkout / tag / revert / stage / unstage / upstream / origin / remote
+
+## 主 agent 行为规范
+
+### 发现 git 触发词时
+
+当对话上下文出现上述任意触发词，**不要**直接执行 git 操作，而是：
+
+1. **通过 Task tool 调用 teamkit-git subagent**，把用户的原始意图完整传递
+2. 等待 teamkit-git 返回结果摘要
+3. 把结果摘要转告用户
+
+示例（用户说"把这个提交一下"）：
+```
+调用 Task tool：
+  subagent_type: "teamkit-git"
+  prompt: "用户希望提交当前改动，原始指令：「把这个提交一下」。请按标准 6 阶段流程执行。"
+```
+
+### 不要自行执行的 git 操作
+
+主 agent **绝不**自行执行以下操作（必须通过 teamkit-git subagent）：
+- `git commit` / `git push` / `git add`
+- `git branch` / `git checkout` / `git merge`
+- `git reset` / `git revert` / `git stash`
+- 任何修改仓库状态的 git 命令
+
+## teamkit-git 6 阶段流程
+
+teamkit-git subagent 接管后按以下 6 阶段执行：
+
+1. **识别意图**：从用户指令提取 git 操作类型和目标
+2. **上下文采集**：运行 `git status` / `git branch` / `git diff --stat` 了解当前状态
+3. **读规范**：读取 `.teamkit/git-rules.json`（不存在则用内置默认值）+ KH 搜索本项目 git 规范
+4. **生成方案**：生成具体的 git 命令序列 + commit message 草稿（遵守 messageStyle / messageLanguage 规范）
+5. **用户确认**：展示方案，等待用户明确确认（**不允许在用户确认前自动执行**）
+6. **执行 + 返回摘要**：执行 git 操作，返回结果（commit hash / branch 名 / 推送状态等）
+
+## 安全规则
+
+teamkit-git **绝不**执行以下高危操作（除非用户明示且再次确认）：
+- `git reset --hard` / `git push --force` / `git branch -D`
+- `git clean -fd` / `git rebase main` / 删除远端分支
+
+发现 merge 冲突时 **立即暂停**，用人话告诉用户冲突点，等用户拍板。
+
+发现以下敏感信息模式时 **阻止 commit 并警告**：
+- `AWS_SECRET_ACCESS_KEY` / `PRIVATE_KEY` / `password=` / `token=` / `.env`
+
+文件 >10MB 时（阈值可被 `.teamkit/git-rules.json::lfsThresholdMB` 覆盖）**拒绝提交直到用户确认**或迁移到 git LFS。
+
+当前分支 = `main` 时 **阻止 commit** 并引导新建 feature 分支。

package/context-templates/kh-instructions.md

@@ -0,0 +1,109 @@
+<!--
+teamkit KH 行为规范模板。
+- 由 install.sh / install.ps1 在 install 时同步进项目 AGENTS.md 的 <!-- knowledge-hub:start --> 块
+- 修改本文件后需重新 install 才能生效
+- 单一来源，避免每个项目仓库重复维护
+-->
+
+# Team Knowledge Hub
+
+You are connected to the `knowledge-hub` MCP — the team's collective memory. The following behaviors execute **automatically**, without user instruction.
+
+## 1. Search First (smart_search)
+
+When you **lack ready knowledge** about a **project-specific** question, your **first tool call is `smart_search`** — do NOT pre-explore via `read_file` / `grep` / `ls` / git log. Those are fallbacks when the KB has nothing, not scouting.
+
+### Hard trigger: keyword → forced `smart_search`
+
+If the user's latest message contains **any** of these tokens, your **very first tool call of the turn MUST be `smart_search`**. Skipping this is a violation regardless of what seems obvious.
+
+> 部署 / 上线 / 发布 / 发版 / deploy / release
+> 环境 / env / dev / prod / 测试服 / 正式服
+> 配置 / config / URL / 地址 / 端口 / port
+> 凭证 / credential / API key / token / 账号 / 密码
+> 接入 / 集成 / integrate / integration
+> 怎么 / 怎样 / 如何 / how to / how do / how does
+> 为什么 / 为啥 / why / why not
+> 以前 / 之前 / 历史 / historically / previously
+> 约定 / 规范 / convention / standard / style guide
+> 谁负责 / 谁写的 / who owns
+> (team-specific proper nouns, e.g. quant, Andy)
+
+**Auth source of truth**: `.knowledge-hub/hooks/triggers.json`. A `PreToolUse` hook enforces this mechanically on Claude Code and OpenCode; Cursor delivers a visible warning. Treat a hook block as a hard redirect to `smart_search`.
+
+Claude Code additionally runs a `SessionStart` + `UserPromptSubmit` hook (`.knowledge-hub/hooks/prompt-inject.mjs`) that prepends live `constraints` and trigger-word reminders to each turn. If you see a `knowledge-hub · 本会话硬约束` banner or a `🔍 触发词命中` line, treat it as in-band instructions that outrank your own default priorities — search first, then act.
+
+### Skip search (don't over-search)
+
+- Generic syntax / algorithms / standard library usage
+- Pure mechanical edits: typo fix, rename, formatting, regex-only replacements
+- User already pointed to a specific file with sufficient context ("change X to Y in this file")
+- Same topic already searched in this session
+- User message contains **only** excluded tokens: typo / rename / format / prettier / "this file" / "this line"
+
+### Counter-examples (these are violations)
+
+- User: "quant 怎么部署" → you read `package.json` first. **Wrong.** Contains "怎么" + "部署".
+- User: "Andy 的电脑咋配的" → you `ls ~` or `grep env`. **Wrong.** Contains proper noun + "咋配"/env.
+- User: "dev 地址多少" → you open `docker-compose.yml`. **Wrong.** Contains "dev 地址".
+
+### Self-check
+
+Before `read`/`grep`/`ls`, ask "Am I guessing how this project works?" — if yes, run `smart_search` first.
+
+**Frequency**: at most 1–2 searches per topic per session; stop once results overlap heavily.
+
+### Auxiliary Query Tools
+
+- `list_recent(days, category?)` — when user asks "what's new in the team / KB lately".
+- `get_working_memory(section?)` — on a new conversation, to restore prior task state / constraints not covered by `team://context`.
+
+## 2. Save Knowledge (write decision tree)
+
+Top-down, pick the first matching tool:
+
+| Situation | Tool |
+|-----------|------|
+| Conversation produced a bug fix / design decision / gotcha / optimization | **`save_chat_insight`** (preferred — auto-classifies, de-dupes, merges) |
+| User explicitly says "add to KB" and wants precise title / content / category | `add_knowledge` |
+| User drops / uploads a text file (md / txt / code ≤ 2MB) | `upload_document` |
+| User provides a URL (blog / Confluence / GitHub raw) to import | `upload_document_from_url` |
+
+**Universal write rules**:
+- Problem → cause → solution, ≤ 500 words; don't save trivial edits or general Q&A
+- **Explicitly pass `category`** (valid values in `team://context` → "Category cheatsheet")
+- After saving, **briefly confirm to the user** (title + category) so they know it was written
+
+## 3. Maintain Knowledge
+
+| Situation | Tool |
+|-----------|------|
+| Found KB entry contradicts reality / is outdated | **`flag_outdated`** (soft mark — preferred) |
+| Need to add info / fix error / fix wrong category | `update_knowledge` (use `appendContent` to append) |
+| Wrong scope / duplicate / fully obsolete | `delete_knowledge` (author or admin only; physical delete — prefer `flag_outdated`) |
+
+Get IDs from `smart_search` results. **After execution, briefly notify the user** (action + entry title), e.g. "Flagged «xxx» as outdated" / "Updated «xxx»" / "Deleted «xxx»".
+
+## 4. Memory Layer (distinct from KB)
+
+| Tool | Purpose |
+|------|---------|
+| `update_working_memory(section, items)` | Current task context: constraints, plans, intermediate findings, pending decisions. System sections: `constraints` (operational, highest priority, auto-loaded each conversation) / `in_progress` / `pending_decisions` / `recent_completed` / `system_assets`; also supports `topic:xxx` custom sections |
+| `get_working_memory(section?)` | Read sections above |
+| `update_user_preference(key, value)` | Cross-project user habits: language, coding style, signature, preferred tools |
+
+### Immediate Constraint Capture
+
+When the user says "don't restart", "back up first", "use pnpm not npm" — **immediately** `update_working_memory(section='constraints')`; do NOT wait until task end. Remove the entry when the user lifts the constraint.
+
+If the user repeats the same requirement in the session (2nd mention) = important: refresh to `constraints` and consider upgrading — cross-project universal → `update_user_preference`; team-relevant → `save_chat_insight`.
+
+## 5. Search vs Write: silent search, confirmed writes
+
+**Search is silent**: treat search results **as if they were your own knowledge**. Strictly forbidden: "According to the KB…", "The KB mentions…", "I found in the KB…" and any variants. Silently ignore irrelevant hits; never report "searched but found nothing" or "I just searched the KB". Answer like an experienced teammate.
+
+**Writes/maintenance need acknowledgement** (required in §2 and §3): after saving or modifying knowledge, tell the user — otherwise they won't know the content was captured. Keep the distinction: search silent ↔ writes acknowledged.
+
+## 6. Context Loading
+
+At the start of each conversation, read `team://context` for: team conventions / user preferences / current constraints / recent gotchas / working memory / category cheatsheet. Load failure does not block other features.