@colin4k1024/tsp 2.4.0

package/skills/context-engineering/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: context-engineering
+description: >
+  项目级上下文工程框架：通过 PROJECT / REQUIREMENTS / ROADMAP / STATE 四层文档
+  为每个任务建立结构化上下文，控制 token 预算，防止上下文腐烂，
+  确保跨会话连续性。与 context-lifecycle 的 L0-L3 层互补。
+origin: gsd-get-shit-done + harness-engineering
+---
+
+# Context Engineering
+
+## 用途
+
+- 为复杂、多会话、多角色任务建立 **结构化项目上下文**，保证每轮 agent 启动时拿到完整且受控的项目背景。
+- 与 `context-lifecycle`（运行时记忆管理）互补：本 skill 管 **项目级文档层**（L3+），`context-lifecycle` 管 **运行时窗口层**（L0-L2）。
+- 控制文档 token 预算，避免"文档越来越多、上下文越来越模糊"的腐烂问题。
+
+## 触发信号
+
+- 新任务 intake 阶段需要建立或刷新项目上下文。
+- `/team-intake`、`/team-plan` 输出后需要落盘为结构化文档。
+- 跨会话恢复时需要快速加载上下文而不丢失关键决策。
+- 多个 agent 并行工作需要共享一致的项目背景。
+- 上下文窗口利用率接近阈值，需裁剪文档到预算范围。
+
+## 四层文档模型
+
+```
+docs/artifacts/{slug}/
+├── PROJECT.md          # 项目愿景、边界、关键假设   (≤ 3000 tokens)
+├── REQUIREMENTS.md     # 范围化需求与验收标准       (≤ 5000 tokens)
+├── ROADMAP.md          # 阶段路线与里程碑           (≤ 3000 tokens)
+└── STATE.md            # 运行时状态：决策、阻塞、进度 (≤ 4000 tokens)
+```
+
+### PROJECT.md — 项目愿景（≤ 3000 tokens）
+
+不变频率最低，只在项目方向调整时更新。
+
+```markdown
+# {Project Name}
+
+## 愿景
+一句话说明项目存在的原因和最终目标。
+
+## 边界
+- In Scope: ...
+- Out of Scope: ...
+
+## 关键假设
+- [ ] 假设 1（待验证 / 已验证 / 已推翻）
+- [ ] 假设 2
+
+## 技术栈
+- 语言 / 框架 / 基础设施
+
+## 利益相关方
+- 角色: 关注点
+```
+
+### REQUIREMENTS.md — 范围化需求（≤ 5000 tokens）
+
+每个 `/team-intake` 结束后由 `product-manager` 或 `tech-lead` 刷新。
+
+```markdown
+# Requirements — {slug}
+
+## 用户故事
+- US-001: 作为…我希望…以便…
+  - AC: 验收标准 1, 2, 3
+
+## 功能需求
+| ID | 需求 | 优先级 | 状态 |
+|----|------|--------|------|
+
+## 非功能需求
+| 维度 | 目标 | 验证方式 |
+
+## 约束
+- 技术约束
+- 业务约束
+- 时间约束
+```
+
+### ROADMAP.md — 阶段路线（≤ 3000 tokens）
+
+里程碑粒度的阶段划分，由 `project-manager` 维护。
+
+```markdown
+# Roadmap — {slug}
+
+## 当前阶段
+Phase N: {name} — {status}
+
+## 阶段划分
+| Phase | 名称 | 关键产出 | 完成标准 | 状态 |
+|-------|------|----------|----------|------|
+
+## 依赖图
+Phase 1 → Phase 2 → Phase 3
+              ↘ Phase 2b ↗
+```
+
+### STATE.md — 运行时状态（≤ 4000 tokens）
+
+频率最高，每个 `/team-execute`、`/team-review`、`/pause` 后刷新。
+
+```markdown
+# State — {slug}
+
+## 最后更新
+{ISO timestamp} by {role}
+
+## 当前焦点
+当前正在推进的工作项。
+
+## 决策日志（最近 10 条）
+| # | 日期 | 决策 | 原因 | 影响 |
+|---|------|------|------|------|
+
+## 阻塞项
+| 阻塞 | Owner | 状态 |
+
+## 进度快照
+| 工作项 | 状态 | 负责角色 | 备注 |
+
+## 下一步
+1. ...
+2. ...
+```
+
+## Token 预算管理
+
+### 预算分配
+
+| 文档 | 上限 | 占上下文比例 | 更新频率 |
+|------|------|-------------|----------|
+| PROJECT.md | 3000 tokens | ~1.5% | 极低 |
+| REQUIREMENTS.md | 5000 tokens | ~2.5% | 低 |
+| ROADMAP.md | 3000 tokens | ~1.5% | 低 |
+| STATE.md | 4000 tokens | ~2% | 高 |
+| **合计** | **15000 tokens** | **~7.5%** | — |
+
+### 超限处理
+
+1. **STATE.md 超限**：只保留最近 10 条决策日志，历史归档到 `docs/memory/decisions.md`。
+2. **REQUIREMENTS.md 超限**：已完成需求标注 `[DONE]` 后迁移到 `docs/artifacts/{slug}/requirements-archive.md`。
+3. **ROADMAP.md 超限**：已完成阶段折叠为单行摘要。
+4. **PROJECT.md 超限**：审查假设列表，移除已验证项。
+
+## 工作流集成
+
+### 写入时机
+
+| 命令 / 事件 | 写入文档 | 操作 |
+|-------------|----------|------|
+| `/team-intake` 完成 | PROJECT.md, REQUIREMENTS.md | 创建或刷新 |
+| `/team-plan` 完成 | ROADMAP.md, STATE.md | 创建或刷新 |
+| `/team-execute` 每步完成 | STATE.md | 更新进度和决策 |
+| `/team-review` 完成 | STATE.md | 更新放行结论 |
+| `/pause` | STATE.md | 写入暂停快照 |
+| `/resume` | — | 读取全部四层作为恢复上下文 |
+| 角色 handoff | STATE.md | 追加交接记录 |
+
+### 读取策略
+
+```
+Agent 启动时加载顺序：
+1. PROJECT.md   → 建立背景
+2. ROADMAP.md   → 确认阶段
+3. STATE.md     → 获取当前焦点和阻塞
+4. REQUIREMENTS.md → 按需参考（仅在需求相关任务时）
+```
+
+### 与既有体系映射
+
+| context-engineering 文档 | Team Skills Platform 既有产物 | 关系 |
+|--------------------------|---------------------|------|
+| PROJECT.md | PRD 背景/约束 + Delivery Plan 版本目标 | 精简聚合 |
+| REQUIREMENTS.md | PRD 用户故事/验收标准 | token 受控子集 |
+| ROADMAP.md | Delivery Plan 工作拆解 | 阶段视图 |
+| STATE.md | Execute Log + docs/memory/decisions.md | 运行时快照 |
+
+## 配套约束
+
+1. 四层文档是 **快速加载视图**，不替代 PRD / Delivery Plan / ADR 等正式交付物。
+2. 预算上限是硬约束：超限时必须裁剪而非放任增长。
+3. STATE.md 的决策日志必须与 `docs/memory/decisions.md` 双向同步。
+4. 多 agent 并行写同一个 STATE.md 时，以最后合并为准；冲突时保留更高信息密度的版本。
+5. 不在这四层文档中存放代码片段、完整测试结果或大段日志——这些属于 L2 归档。
+
+## 验证标准
+
+- [ ] 四层文档均在 token 预算之内
+- [ ] STATE.md 最后更新时间 < 当前会话开始时间（即已经在会话初始化时加载）
+- [ ] 决策日志条数 ≤ 10 条，超出部分已归档
+- [ ] 已完成需求有 `[DONE]` 标记或已归档
+- [ ] `/resume` 能在 < 15s 内加载全部四层并展示当前焦点

package/skills/context-lifecycle/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: context-lifecycle
+description: >
+  上下文生命周期管理总览：四层记忆架构（L0-L3）、任务阶段感知、
+  渐进压缩策略、按需召回与四分区预算模型。
+origin: harness-engineering
+---
+
+# Context Lifecycle Skill
+
+管理 Claude Code 长时多轮任务中的上下文生命周期，避免压缩导致关键细节丢失。
+
+## 架构概览
+
+```
+┌──────────────────────────────────────────────────────┐
+│                 上下文窗口 (200K tokens)                │
+│                                                        │
+│  ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌────────┐ │
+│  │  System   │ │  Ledger  │ │  Working   │ │ Buffer │ │
+│  │  (10%)    │ │  (10%)   │ │  (65%)     │ │ (15%)  │ │
+│  │ protected │ │ protected│ │ 主工作区    │ │ 溢出区  │ │
+│  └──────────┘ └──────────┘ └────────────┘ └────────┘ │
+└──────────────────────────────────────────────────────┘
+         ↕ 渐进压缩                ↕ 按需召回
+┌──────────────────────────────────────────────────────┐
+│  L1: 摘要 + L2 引用   →   L2: 全文归档 (索引)         │
+│  (替换 L0 原文)             (~/.claude/memory/)       │
+│                                                        │
+│  L3: 项目记忆 (跨会话)  →  docs/memory/ + Phase Ledger │
+└──────────────────────────────────────────────────────┘
+```
+
+## 四层记忆模型
+
+| 层级 | 名称 | 位置 | 内容 | 生命周期 |
+|------|------|------|------|----------|
+| L0 | 工作记忆 | 上下文窗口 | 当前对话、工具结果、代码 | 当前会话 |
+| L1 | 摘要记忆 | 上下文窗口 (替换 L0) | 压缩摘要 + L2 归档引用 | 当前会话 |
+| L2 | 详情归档 | `~/.claude/memory/sessions/{sid}/` | 完整原文、关键词索引 | 本地持久 |
+| L3 | 项目记忆 | `docs/memory/` | Phase Ledger、决策日志、经验 | 跨会话持久 |
+
+## 渐进压缩策略
+
+压缩基于 **Working Zone** 使用率，而非整体上下文使用率：
+
+| Working 使用率 | 压缩级别 | 操作 |
+|----------------|----------|------|
+| < 60% | 无 | 保持 L0 原文 |
+| 60% | L0→L1 | 摘要工具结果、旧对话，原文归档到 L2 |
+| 75% | L1→L2 | 摘要 L1 内容，更老的摘要归档到 L2 |
+| 90% | L2→L3 | 紧急压缩，决策提升到项目记忆 |
+
+### 阶段感知优先级
+
+压缩时的保留/归档决策受当前任务阶段影响：
+
+| 阶段 | 优先保留 | 优先归档 |
+|------|----------|----------|
+| Planning | 需求、边界、约束 | 探索性讨论 |
+| Design | 架构决策、接口契约 | 备选方案分析 |
+| Implementation | 当前文件、测试结果 | 设计讨论 |
+| Testing | 测试结果、缺陷 | 实现细节 |
+| Review | 评审结论、修改建议 | 测试细节 |
+
+## 核心组件
+
+### 库模块 (`scripts/lib/`)
+
+| 模块 | 职责 |
+|------|------|
+| `phase_tracker.py` | 任务阶段状态机，多信号检测（命令 / handoff / 工具启发） |
+| `phase_ledger.py` | 阶段交接账页，在阶段切换时生成结构化 Markdown |
+| `context_budget.py` | 四分区预算模型，Zone-aware 压缩级别判定 |
+| `context_archiver.py` | L2 归档写入、关键词索引、去重、批量归档 |
+| `context_recall.py` | 按需召回：关键词 / 阶段 / 类型 / 决策多维检索 |
+| `context_priority.py` | 上下文元素优先级评分（已有） |
+
+### Hooks (`scripts/hooks/`)
+
+| Hook | 触发点 | 作用 |
+|------|--------|------|
+| `session_start.py` | 会话开始 | 加载 Phase Timeline、未解决项、决策摘要 |
+| `pre_compact.py` | 压缩前 | 分类元素为 keep/summarize/archive/discard |
+| `suggest_compact.py` | 压缩建议 | 根据 Working Zone 使用率推荐渐进压缩策略 |
+
+### Skills (`skills/`)
+
+| Skill | 用途 |
+|-------|------|
+| `context-recall` | `/recall` 命令，按需从 L2 归档和 Phase Ledger 检索 |
+| `context-lifecycle` | 本文档，整体架构说明 |
+| `strategic-compact` | 已有的 trigger-based 上下文重组能力 |
+
+## 数据流
+
+### 写入路径
+
+```
+对话/工具结果 (L0)
+    ↓ Working Zone > 60%
+pre_compact → categorize as "archive"
+    ↓
+context_archiver.archive_and_index()
+    ├── 写入 L2 文件: ~/.claude/memory/sessions/{sid}/archived/{hash}.md
+    ├── 更新索引: ~/.claude/memory/sessions/{sid}/index.json
+    └── 返回 L1 摘要 (替换上下文中的原文)
+    
+阶段切换时
+    ↓
+phase_ledger.generate_ledger() + save_ledger()
+    ├── 写入 L3: docs/memory/sessions/{sid}/phase-{N}-{name}.md
+    └── 更新索引: /tmp/harness-phase-ledger-{sid}.json
+```
+
+### 读取路径
+
+```
+会话启动
+    ↓
+session_start → get_recall_context_for_session_start()
+    ├── 读取 Phase Ledger 索引 → phase_timeline
+    ├── 统计未解决项 → pending_items
+    └── 统计决策数 → recall_hint
+
+用户请求 /recall
+    ↓
+context_recall → recall_by_keyword/phase/type/decisions()
+    ├── 搜索 L2 索引 (index.json)
+    ├── 加载 L2 完整内容
+    └── 搜索 Phase Ledger
+```
+
+## 使用指南
+
+### 自动行为（无需干预）
+
+1. **会话启动**自动加载 Phase Timeline 和未解决项
+2. **压缩时**自动按阶段优先级归档而非丢弃
+3. **阶段切换时**自动生成 Phase Ledger
+
+### 手动操作
+
+1. **`/recall keyword`** — 从归档中按关键词搜索
+2. **`/recall phase:design`** — 查看 design 阶段的完整交接记录
+3. **`/recall decisions`** — 查看所有决策链路
+4. **`/recall timeline`** — 查看阶段时间线
+
+### 与现有能力的协同
+
+- `strategic-compact`: 本系统的 L0→L1 压缩替代了 strategic-compact 的全量压缩，两者可共存
+- `error-experience-library`: 错误经验在 L3 层跨会话持久保存
+- `continuous-learning`: instinct 产物不受压缩影响，已在 L3 层
+
+## 配置
+
+可通过环境变量或 hooks.json 参数调整：
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| Zone ratios | 10/10/65/15 | System/Ledger/Working/Buffer 分区比例 |
+| L0→L1 threshold | 60% | Working Zone 使用率触发 L0→L1 |
+| L1→L2 threshold | 75% | Working Zone 使用率触发 L1→L2 |
+| L2→L3 threshold | 90% | Working Zone 使用率触发 L2→L3 |

package/skills/context-recall/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: context-recall
+description: >
+  按需召回已归档的上下文细节：支持按关键词、阶段、类型和决策维度检索，
+  从 L2 归档和 Phase Ledger 中恢复压缩丢失的信息。
+origin: harness-engineering
+---
+
+# Context Recall Skill
+
+按需召回已归档的上下文细节，从 L2 归档索引和 Phase Ledger 中恢复压缩过程中被移出工作记忆的信息。
+
+## 何时激活
+
+- 用户输入 `/recall` 命令
+- 需要恢复早期对话中的代码细节、工具输出或决策上下文
+- 当前上下文中缺少之前阶段的关键信息
+- 用户提到"之前讨论过"、"之前的方案"、"找一下之前的…"等表述
+
+## 使用方式
+
+### 基本命令
+
+```
+/recall <keyword>              # 按关键词搜索归档
+/recall phase:<phase_name>     # 按阶段召回（如 phase:implementation）
+/recall type:<element_type>    # 按类型召回（如 type:tool_result）
+/recall decisions              # 召回所有决策记录
+/recall timeline               # 显示阶段时间线概览
+```
+
+### 组合查询
+
+```
+/recall phase:design keyword   # 在 design 阶段中搜索关键词
+/recall type:code_change api   # 在代码变更中搜索 api 相关内容
+```
+
+## 核心功能
+
+### 1. 关键词召回
+
+从 L2 归档索引中按关键词匹配，返回相关的归档元素摘要和完整内容引用。
+
+**工作原理**:
+1. 搜索 `~/.claude/memory/sessions/{sid}/index.json` 中的 keywords 字段
+2. 按匹配度排序返回结果
+3. 提供 L1 摘要和 L2 完整内容的访问路径
+
+### 2. 阶段召回
+
+从 Phase Ledger 中按阶段名称检索，返回该阶段的结构化交接记录。
+
+**输出包含**:
+- 阶段目标与完成情况
+- 关键决策列表
+- 代码变更清单
+- 未解决项
+
+### 3. 决策召回
+
+跨所有阶段收集决策记录，构建完整的决策链路。适用于需要理解"为什么这样做"的场景。
+
+### 4. 类型召回
+
+按上下文元素类型检索：
+- `tool_result`: 工具执行结果
+- `assistant_message`: 助手回复
+- `user_message`: 用户消息
+- `code_change`: 代码变更
+- `decision`: 决策记录
+
+## 技术实现
+
+### 依赖模块
+
+| 模块 | 路径 | 职责 |
+|------|------|------|
+| `context_recall` | `scripts/lib/context_recall.py` | 召回逻辑核心 |
+| `context_archiver` | `scripts/lib/context_archiver.py` | L2 归档索引读取 |
+| `phase_ledger` | `scripts/lib/phase_ledger.py` | Phase Ledger 读取 |
+
+### 数据源
+
+| 源 | 路径 | 内容 |
+|----|------|------|
+| L2 归档索引 | `~/.claude/memory/sessions/{sid}/index.json` | 关键词索引、元素摘要 |
+| L2 归档文件 | `~/.claude/memory/sessions/{sid}/archived/*.md` | 完整归档内容 |
+| Phase Ledger | `docs/memory/sessions/{sid}/phase-*.md` | 阶段交接记录 |
+| Ledger 索引 | `/tmp/harness-phase-ledger-{sid}.json` | Ledger 快速索引 |
+
+### 调用示例
+
+```python
+from scripts.lib.context_recall import (
+    recall_by_keyword,
+    recall_by_phase,
+    recall_by_type,
+    recall_decisions,
+    get_phase_timeline,
+    format_recall_results,
+)
+
+# 按关键词
+results = recall_by_keyword(session_id, "api contract")
+print(format_recall_results(results))
+
+# 按阶段
+results = recall_by_phase(session_id, "design", project_path)
+print(format_recall_results(results))
+
+# 所有决策
+results = recall_decisions(session_id, project_path)
+print(format_recall_results(results))
+
+# 阶段时间线
+timeline = get_phase_timeline(session_id, project_path)
+print(timeline)
+```
+
+## 输出格式
+
+召回结果以 Markdown 格式返回:
+
+```markdown
+## 召回结果: "api contract"
+
+### 匹配 1: [tool_result] API 设计讨论
+- **阶段**: design
+- **归档时间**: 2025-01-15 14:30
+- **摘要**: 确定了 RESTful API 契约，包括认证方式和错误码规范...
+- **完整内容**: ~/.claude/memory/sessions/abc123/archived/a1b2c3d4e5f6.md
+
+### 匹配 2: [decision] 选择 OpenAPI 3.0
+- **阶段**: design
+- **摘要**: 决定使用 OpenAPI 3.0 作为 API 契约格式...
+```
+
+## 与其他能力的关系
+
+| 能力 | 关系 |
+|------|------|
+| `strategic-compact` | compact 时归档 → recall 时恢复 |
+| `pre_compact` hook | 产生 L2 归档和索引 → recall 消费 |
+| `session_start` hook | 启动时自动加载 Phase Timeline |
+| `phase_tracker` | 提供阶段上下文用于精确召回 |
+| `phase_ledger` | 提供结构化阶段交接 → recall 检索 |
+
+## 限制
+
+- 召回内容来自归档，可能不包含最近未被压缩的对话
+- 关键词匹配基于词频提取，复杂语义查询可能不精确
+- Phase Ledger 依赖阶段检测正确性，手动阶段切换可能遗漏
+- L2 归档文件存储在本地，跨机器不可用

package/skills/continuous-agent-loop/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: continuous-agent-loop
+description: Patterns for continuous autonomous agent loops with quality gates, evals, and recovery controls.
+origin: ECC
+---
+
+# Continuous Agent Loop
+
+This is the v1.8+ canonical loop skill name. It supersedes `autonomous-loops` while keeping compatibility for one release.
+
+## Loop Selection Flow
+
+```text
+Start
+  |
+  +-- Need strict CI/PR control? -- yes --> continuous-pr
+  |
+  +-- Need RFC decomposition? -- yes --> rfc-dag
+  |
+  +-- Need exploratory parallel generation? -- yes --> infinite
+  |
+  +-- default --> sequential
+```
+
+## Combined Pattern
+
+Recommended production stack:
+1. RFC decomposition (`ralphinho-rfc-pipeline`)
+2. quality gates (`plankton-code-quality` + `/quality-gate`)
+3. eval loop (`eval-harness`)
+4. session persistence (`nanoclaw-repl`)
+
+## Failure Modes
+
+- loop churn without measurable progress
+- repeated retries with same root cause
+- merge queue stalls
+- cost drift from unbounded escalation
+
+## Recovery
+
+- freeze loop
+- run `/harness-audit`
+- reduce scope to failing unit
+- replay with explicit acceptance criteria

package/skills/continuous-learning/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: continuous-learning
+description: >
+  基于 instinct 的持续学习系统，通过 hooks 观察会话，创建带置信度评分的 atomic instincts，
+  并将高置信度 instinct 演进为 skills/commands/agents。v2.1 增加项目级 instincts 防止跨项目污染。
+origin: adapted from ECC
+version: 2.1.0
+---
+
+# Continuous Learning v2.1 - Instinct-Based Architecture
+
+一个高级学习系统，通过 atomic "instincts" 将 Claude Code 会话转化为可重用知识。
+
+**v2.1** 增加 **项目级 instincts** — React 模式保留在 React 项目中，Python 约定保留在 Python 项目中，通用模式（如"始终验证输入"）全局共享。
+
+## 何时激活
+
+- 设置从 Claude Code 会话自动学习
+- 配置基于 hooks 的行为提取
+- 调优学习行为的置信度阈值
+- 审查、导出或导入 instinct 库
+- 将 instincts 演进为完整 skills、commands 或 agents
+- 管理项目级 vs 全局 instincts
+- 将 instincts 从项目级提升到全局级
+
+## Instinct 模型
+
+一个 instinct 是一个小的学习行为：
+
+```yaml
+---
+id: prefer-component-colocation
+trigger: "当多个组件使用相同状态时"
+confidence: 0.7
+domain: "frontend-architecture"
+source: "session-observation"
+scope: project
+project_id: "a1b2c3d4e5f6"
+project_name: "points-frontend"
+---
+
+# 组件状态共置
+
+## 行为
+当多个组件使用相同状态时，考虑将状态提升到共同祖先。
+
+## 证据
+- 在 5 个实例中观察到状态提升模式
+- 用户在 2026-03-29 将组件本地状态改为共享状态
+```
+
+**属性**:
+- **Atomic** -- 一个 trigger，一个 action
+- **Confidence-weighted** -- 0.3 = 试探性，0.9 = 几乎确定
+- **Domain-tagged** -- code-style, testing, git, debugging, workflow 等
+- **Evidence-backed** -- 跟踪创建它的观察
+- **Scope-aware** -- `project`（默认）或 `global`
+
+## 存储结构
+
+```
+~/.claude/homunculus/
++-- projects.json           # 项目注册表: hash -> name/path
++-- observations.jsonl      # 全局观察（fallback）
++-- instincts/
+|   +-- personal/          # 全局自动学习的 instincts
+|   +-- inherited/         # 全局导入的 instincts
++-- evolved/
+|   +-- agents/           # 全局生成的 agents
+|   +-- skills/           # 全局生成的 skills
+|   +-- commands/         # 全局生成的 commands
++-- projects/
+    +-- a1b2c3d4e5f6/    # 项目 hash（来自 git remote URL）
+        +-- project.json    # 项目元数据
+        +-- observations.jsonl
+        +-- instincts/
+        |   +-- personal/  # 项目特定自动学习
+        |   +-- inherited/  # 项目特定导入
+        +-- evolved/
+            +-- skills/
+            +-- commands/
+            +-- agents/
+```
+
+## 项目检测
+
+系统自动检测当前项目：
+
+1. **`CLAUDE_PROJECT_DIR` env var**（最高优先级）
+2. **`git remote get-url origin`** -- hash 生成项目 ID
+3. **`git rev-parse --show-toplevel`** -- fallback
+4. **全局 fallback** -- 如果未检测到项目，instincts 进入全局范围
+
+## 置信度评分
+
+| 分数 | 含义 | 行为 |
+|------|------|------|
+| 0.3 | 试探性 | 建议但不强制 |
+| 0.5 | 中等 | 相关时应用 |
+| 0.7 | 强 | 自动批准应用 |
+| 0.9 | 几乎确定 | 核心行为 |
+
+**置信度增加**当:
+- 模式被重复观察
+- 用户不纠正建议的行为
+- 相似 instincts 同意
+
+**置信度减少**当:
+- 用户明确纠正行为
+- 模式长时间未观察到
+- 出现矛盾证据
+
+## 与 Skills 的区别
+
+| 特性 | Skills | Instincts |
+|------|--------|-----------|
+| 粒度 | 完整工作流 | Atomic 行为 |
+| 触发 | 手动调用 | 自动观察 |
+| 置信度 | 无 | 0.3-0.9 |
+| 演化 | 直接成为 skill | 先 instinct 再 cluster |
+
+## 相关工具
+
+- `scripts/lib/memory_store.py` - 底层存储接口
+- Error Experience Library - 错误模式的专门 instinct
+
+## 命令接入
+
+- `/instinct-status` - 显示学习的 instincts
+- `/evolve` - 将 instincts 聚类为 skills/commands
+- `/instinct-export` - 导出 instincts 到文件
+- `/instinct-import` - 从文件导入 instincts
+- `/promote` - 将项目 instincts 提升到全局
+
+## 最佳实践
+
+1. **观察** -- 启用 hooks 捕获所有工具调用
+2. **分析** -- 定期运行 observer agent 分析观察
+3. **演进** -- 将高置信度 instincts 演进为 skills
+4. **分享** -- 通过导出/导入在团队中共享 instincts