@sushanglewis/lincoln 1.5.0 → 1.5.2

package/framework/CLAUDE.md

@@ -0,0 +1,140 @@
+# Lincoln — Agent Contract
+
+本文件定义 Lincoln 仓库中 Claude Code Agent 的契约。它作为 Claude Code 项目级系统提示的一部分，由 `.claude/hooks/on-session-start.sh` 在会话启动时自动注入当前阶段上下文，Agent 不需要手动“先读 README 再读 CLAUDE.md”。
+
+如果你是 Lincoln 模板的使用者，请从根目录 [`README.md`](README.md) 开始；如果你是框架开发者，才需要阅读本文件。
+
+## `.claude/` 的定位
+
+`.claude/` 是 Lincoln 在 Claude Code 机制下的**抽象系统提示层**，包含：
+
+- `agents/` — Agent 角色模板（default、pm、designer、engineer、qa、researcher 等）。
+- `skills/` — Lincoln 原生技能与外部技能依赖清单（`dependencies.yaml`）；阶段到技能的映射由 `.claude/stages/<stage-id>.yaml` 的 `skills` 字段派生。
+- `stages/` — 阶段上下文（每个阶段一个 `<stage-id>.yaml`，角色、技能、门控与产物约定内联其中）。
+- `workflows/` — SOP 工作流模板定义与索引 [`README.md`](.claude/workflows/README.md)。
+- `templates/issue-package/` — issue 工作包模板（只读；init 仅读取 `workflow-stage.yaml` 初始化实例，其余 `.tpl` 供 Agent 按需参考生成文档，不复制进工作包）。
+- `schemas/` — JSON Schema 校验。
+- `hooks/` — 生命周期 hooks，由 `.claude/settings.json` 自动挂接。
+
+这些文件不描述某个具体 issue 的执行状态，而是提供**角色行为、阶段校验、技能路由、工作流模板**等抽象规则。具体 issue 的状态和产物保存在 `{process_slug}/workflow-stage.yaml` 及其同目录工作包中。
+
+## Session Startup Protocol
+
+每个 Agent 进入 Lincoln 会话时，Claude Code hooks 已经自动完成以下加载：
+
+1. 依赖检测（`.claude/skills/dependencies.yaml`）。
+2. 解析当前分支的 `{process_slug}/workflow-stage.yaml`。若不存在则回退到 legacy `.claude/workflow-state.yaml`。
+3. 读取 `current_run.current_stage` 并加载 `.claude/stages/<current_stage>.yaml`（角色、技能、门控与上下文内联其中）。
+4. 读取上一个 node 的 handoff 文档。
+5. 输出 Lincoln 状态摘要。
+
+Agent 启动后应：
+
+1. 检查 hook 输出中是否包含「=== Lincoln 开场引导 ===」块：若有，先执行开场引导流程（`.claude/skills/lc-workflow-router/prompts/intake-prompt.md`：摸排 → 判断 → Johari 确认），经人类确认目标与执行路径后再继续。
+2. 简要汇报当前阶段、已加载上下文、推荐技能、等待对象、下一步动作。
+3. 运行 `python3 scripts/stage_loader.py --stage <current_stage> --action validate-entry` 进行准入校验。
+4. 根据当前阶段和上下文继续工作。
+
+如果 `.claude/workflow-stage.yaml` 存在但 `{process_slug}/workflow-stage.yaml` 不存在，说明需要迁移或初始化 issue 工作包；请提示人类运行：
+
+```bash
+scripts/init-lincoln-branch.sh --issue-number <number>
+```
+
+## 模板 vs 实例：状态文件
+
+必须区分以下文件：
+
+| 文件 | 性质 | 用途 |
+|------|------|------|
+| `.claude/templates/issue-package/workflow-stage.yaml` | **模板** | 只读。`init-lincoln-branch.sh` 复制它并填入 issue 专属信息。 |
+| `.claude/templates/solo-workflow-context.yaml` | **模板** | 只读。`scripts/lincoln_workflow.py start`（solo 模式）渲染它生成 session 实例。 |
+| `{process_slug}/workflow-stage.yaml` | **实例（team）** | issue 运行时的真实状态文件，人类-human、人类-Agent、Agent-Agent 之间共享的阶段交接协议。 |
+| `.context/workflow/<name>.yaml` | **实例（solo）** | session 级 solo 工作流状态文件，gitignored，跟随 conductor workspace/session 生命周期，不跨成员共享。 |
+
+工作流通过 `lc-wf-*` 命令（底层 `scripts/lincoln_workflow.py`）启动：`lc-wf-list` 列出所有工作流及其 `execution_mode`；solo 工作流生成 `.context/workflow/<name>.yaml`，team 工作流转发 `init-lincoln-branch.sh` 生成 `{process_slug}/workflow-stage.yaml`。Agent 只应读取和更新**实例**文件，不应直接修改模板。
+
+状态解析优先级（`scripts/lincoln_paths.resolve_state_path`）：显式参数/`LINCOLN_STATE_FILE` > team issue-package > solo `.context/workflow/` > `.claude/` 回退。solo 实例由 `.claude/hooks/on-session-start.sh` 在会话启动时自动注入上下文。
+
+## Issue 工作包
+
+每个 issue 对应一个分支（命名约定 `issue-<N>`，N 为 GitHub issue 编号）和一个工作包目录（默认 `{process_slug}=issue-<N>`）：
+
+```
+issue-<N>/
+├── workflow-stage.yaml          # 阶段状态与 handoff 协议
+├── documents.yaml               # 文档索引：各阶段产物与 human 确认状态（自动生成）
+├── recordings/                  # 原始录音（只读）
+├── interviews/<session-id>/
+├── requirements/<session-id>/
+├── designs/<design-id>/
+├── openspec/changes/
+├── docs/research/
+└── handoffs/
+```
+
+过程文档随 feature 分支传递，不合并到 `main`。Agent 在任何阶段产生的产物都应写入 `{process_slug}/` 下的对应目录，并可通过 `scripts/stage_loader.py --stage <stage> --action record-artifacts` 将产物路径持久化回 `{process_slug}/workflow-stage.yaml`。每次状态保存都会自动刷新工作包根目录的 `documents.yaml` 文档索引（由 `scripts/lincoln_documents.py` 生成），Agent 开始工作前应先读它了解工作包内已有文档及其 human 确认状态。文档模板（`.tpl`）只读地保留在 `.claude/templates/issue-package/` 下，初始化时不再复制进工作包；Agent 需要生成文档时参考对应 `.tpl` 格式直接在工作包目录内撰写。
+
+## Human Gate Rules
+
+- `human_gate: true` 的步骤不能跳过。
+- 必须获得人类 PM 的显式 `confirm` 或已审批标记。
+- 在 `human_gate: true` 阶段，Agent 必须直接向人类 PM 发送消息，不得用 `TaskCreate`/`TaskUpdate` 暂存或拆分“发消息”动作。
+- 在 human_gate 阶段，子技能仅用于探索或结构化，不得替代人类确认。
+
+## Handoff Protocol
+
+暂停或切换窗口时：
+
+```bash
+python3 scripts/stage_loader.py --stage <current_stage> --action handoff-report
+```
+
+更新 `.context/lc-handoff-<stage>.md` 或 `{process_slug}/handoffs/` 文档。人类 PM 确认后：
+
+```bash
+python3 scripts/stage_loader.py --stage <current_stage> --action approve-gate
+```
+
+标记该阶段 gate 审批通过。
+
+## Observability Reporting
+
+每个回复必须简要说明：
+
+- 当前阶段
+- 本次调用使用的技能
+- 产物位置或修改的文件
+- 校验状态（entry passed / exit pending / human gate waiting）
+
+## Skill Invocation Rules
+
+- 通过 `Skill` 工具调用技能，当前阶段可用技能由 `.claude/stages/<current_stage>.yaml` 的 `skills` 字段定义。
+- 不得用技能调用替代 `human_gate`。
+- 实施类技能（如 `subagent-driven-development`、`executing-plans`）必须在 PM 明确批准后才能调用。
+- `lc-workflow-router` 在两种时机触发：(a) 会话开场引导（hook 注入开场引导块，或 `current_stage: not_started`）时先执行 intake 流程；(b) `{process_slug}/workflow-stage.yaml` 中 `current_run.workflow_template` 为空时选择工作流模板。
+- 技能/命令入口统一为 `lc-*` 前缀(旧 `lincoln-*` 已移除);codex/opencode 适配产物由 `scripts/lincoln_harness_adapter.py` 从 `.claude/` 派生,不要手改生成文件,改动事实源后运行 `python3 scripts/lincoln-setup.py generate-harness --harness <name>`。
+
+## 核心原则
+
+1. **工作流优先**：任何操作必须符合当前阶段及其校验规则。
+2. **人类门控不可跳过**：`human_gate: true` 必须获得人类 PM 显式确认。
+3. **产物可追溯**：每个需求、每个功能都必须能关联回原始访谈、OpenSpec 变更、GitHub Issue/PR。
+4. **知识库双轨维护**：每个合并的 issue 必须同时沉淀业务知识和技术知识到 Obsidian vault。
+5. **不修改原始录音**：`{process_slug}/recordings/` 中的文件只读。
+6. **Pencil 原型受控处理**：`.pen` 文件只能通过 Pencil 应用或 Pencil 工具处理。
+7. **只更新实例状态**：永远不要直接修改 `.claude/templates/issue-package/workflow-stage.yaml`。
+8. **自然语言优先**：Lincoln 是 AI-Native 工作流，人类用自然语言或 `/lc-*` 技能表达意图即可，永远不应被要求亲自在终端输入 `python3 scripts/...` 命令；所有脚本调用由 Agent 代为执行并翻译结果。
+
+## 沟通风格
+
+- 使用中文与人类 PM 交流。
+- 汇报进度时简洁，重点说明当前步骤、产物位置、下一步需要人类做什么。
+- 不确定时暂停并提问，不猜测。
+
+## 相关文件
+
+- [`README.md`](README.md) — 用户快速开始指南。
+- [`.claude/workflows/README.md`](.claude/workflows/README.md) — 工作流模板索引。
+- [`.claude/stages/`](.claude/stages/) — 阶段注册表与技能路由（每个阶段一个 `<stage-id>.yaml`，其 `skills` 字段派生阶段到技能的映射）。
+- [`.claude/agents/default.md`](.claude/agents/default.md) — Agent 行为总则。

package/framework/CONTRIBUTING.md

@@ -0,0 +1,219 @@
+# Contributing to Lincoln
+
+欢迎为 Lincoln 贡献代码、文档、测试、工作流模板、Agent 角色与 skills。本文件同时约束**人类贡献者**与**Agent 贡献者**，提交 PR 前请完整阅读。
+
+## 目录
+
+- [Lincoln 的范围](#lincoln-的范围)
+- [核心 vs 领域包边界](#核心-vs-领域包边界)
+- [贡献者护栏（PR 硬性要求）](#贡献者护栏pr-硬性要求)
+- [如何提交 Issue](#如何提交-issue)
+- [如何提交 PR](#如何提交-pr)
+- [本地开发环境](#本地开发环境)
+- [测试分层约定](#测试分层约定)
+- [修改 stage / skill / agent 契约时](#修改-stage--skill--agent-契约时)
+- [如何新增工作流模板](#如何新增工作流模板)
+- [如何新增 Agent 角色](#如何新增-agent-角色)
+- [如何新增 Skill](#如何新增-skill)
+- [如何新增 Harness 适配](#如何新增-harness-适配)
+- [发布前验收](#发布前验收)
+- [获得帮助](#获得帮助)
+
+## Lincoln 的范围
+
+Lincoln 的目标是为 AI-Native 研发工作流提供一套**可复用、可扩展、可审计**的元模型与基础设施。我们借鉴 superpowers 的核心零依赖原则，对范围保持严格纪律。
+
+## 核心 vs 领域包边界
+
+- **核心**：阶段/门控/路由器元模型 + 工作流引擎 + harness 适配器
+  - `.claude/stages/`
+  - `.claude/schemas/`
+  - `.claude/harnesses/`
+  - `.claude/hooks/`
+  - `.claude/settings.json`
+  - `scripts/`（通用基础设施脚本）
+
+- **领域包**：垂直能力，属于可选扩展，不进入核心判断标准
+  - `interview-to-knowledge` 工作流
+  - `oss-first-design` 工作流
+  - `tools/lincoln-record/`
+  - 特定行业的 agent 角色或 skills
+
+判断标准：**"这对完全不同项目的人有用吗？"** 如果答案为否，就不进核心。
+
+**默认规则**：新能力优先做成独立 skill 或工作流模板，而不是修改核心元模型。
+
+## 贡献者护栏（PR 硬性要求）
+
+1. **PR 模板必填**：使用 `.github/pull_request_template.md`，逐项填写，不留空。
+2. **先查重**：提交前搜索已有 issue/PR，确认不与进行中的工作重复（`gh pr list` / issue 搜索）。
+3. **披露生成方式**：PR 描述中说明生成所用的模型、harness 与版本（如 `claude-fable-5 + Claude Code`）。
+4. **一个 PR 只解决一个问题**：混合多个不相关改动的 PR 会被要求拆分。
+5. **human_gate 不可跳过**：任何 PR 不得移除或绕过阶段门控与 human 确认环节。
+6. **不手改生成产物**：codex / opencode 适配产物由 `scripts/lincoln-setup.py generate-harness` 自动生成，**不要手动编辑**。
+7. **同步更新文档**：修改命令表、工作流、角色、skills 时，同步更新 `README.md`、`USAGE.md`、`.claude/workflows/README.md` 等用户/贡献者文档。
+
+## 如何提交 Issue
+
+1. 使用 `.github/ISSUE_TEMPLATE/` 中的模板。
+2. 清晰描述问题、复现步骤、期望行为与实际行为。
+3. 如果是功能请求，请先说明它解决了什么具体问题，以及为什么属于 Lincoln 的核心或推荐领域包。
+4. 如果是文档问题，请标注 `documentation` 标签。
+
+## 如何提交 PR
+
+1. **Fork 仓库**（如果是外部贡献者）或从 `main` 切出 feature 分支。
+2. **命名分支**：非 issue 驱动的小改动可用 `docs/xxx`、`fix/xxx`、`feat/xxx`；issue 驱动的改动使用 `issue-<N>`。
+3. **小步提交**：每个 commit 只解决一个最小完整问题，commit message 遵循现有风格。
+4. **本地验证**：
+   - 运行 `bash scripts/static-check.sh`
+   - 运行 `pytest tests/`
+   - 如果修改了 stage/skill/agent，运行 benchmark 并附前后对比
+5. **填写 PR 模板**：逐项填写，不遗漏。
+6. **等待审查**：维护者会进行 code review，必要时要求补充测试或文档。
+7. **合并后**：如果是 issue 工作包，按 Lincoln 流程把过程知识同步到 `knowledge/` vault。
+
+## 本地开发环境
+
+### 必需依赖
+
+- `python3` ≥ 3.10
+- `node` ≥ 20
+- `gh` CLI（已登录）
+- `openspec` CLI
+
+### 可选依赖
+
+- `ffmpeg`（录音转写）
+- Rust 工具链（`cargo`，构建 `tools/lincoln-record/`）
+- `Pencil`（原型设计）
+
+### 初始化
+
+```bash
+python3 scripts/init-project.sh
+```
+
+或使用新的全局 CLI：
+
+```bash
+npm install -g @sushanglewis/lincoln
+lincoln install
+```
+
+旧版 `npx lincoln-install` 仍可用但已弃用。
+
+### 运行测试
+
+```bash
+# 全部测试
+pytest tests/
+
+# 基础设施测试
+python3 scripts/run-infrastructure-tests.py
+
+# 静态检查
+bash scripts/static-check.sh
+
+# README 约束
+pytest tests/test_readme_natural_language.py
+```
+
+## 测试分层约定
+
+- `tests/`：**确定性、非 LLM** 的契约与单元测试，进 CI（`static-check.sh`），必须全绿。
+- benchmark / eval（`scripts/lincoln_benchmark*.py`）：**LLM 行为评测**，慢且非确定，手动触发，不阻塞 CI。
+
+新增测试时：
+
+- 优先覆盖契约与边界条件，而不是端到端行为。
+- 如果测试需要读取 `.claude/` 文件，使用项目根目录的相对路径，并在 `conftest.py` 中提供 fixtures。
+- 不要引入需要外部 LLM 调用的测试到 `tests/`。
+
+## 修改 stage / skill / agent 契约时
+
+这些文件是"塑造 agent 行为的代码"，按 eval 门禁规范修改：
+
+1. 修改 `.claude/stages/*.yaml`、`.claude/skills/**`、`.claude/agents/**` 前后，跑一遍 benchmark，在 PR 描述中附前后对比（无回归）。
+2. 升级外部 skills 的 pin（`dependencies.yaml`）时同样要求 benchmark 验证（见该文件头部注释的升级流程）。
+3. 修改后运行 `python3 scripts/lincoln_command_map.py --refresh` 重新生成命令表，并运行相关测试。
+
+## 如何新增工作流模板
+
+1. 在 `.claude/workflows/` 创建 `<workflow-name>.yaml`，声明 `execution_mode: solo|team`。
+2. 遵循 `.claude/schemas/workflow-template.schema.json` 的字段约定。
+3. 运行 `python3 scripts/lincoln_command_map.py --refresh` 自动登记 `lc-wf-<name>` 命令。
+4. 运行 `python3 scripts/lincoln-setup.py generate-harness --harness codex --harness opencode` 重新生成适配产物。
+5. 在 `.claude/skills/lc-wf/SKILL.md` 的命令映射表中补充触发词。
+6. 更新 `.claude/workflows/README.md` 的快速路由表与模板详解。
+7. 如果该工作流面向最终用户，在 `USAGE.md` 中补充说明。
+
+## 如何新增 Agent 角色
+
+1. 在 `.claude/agents/` 创建 `<role>.md`，参考 `_contract.md` 与现有角色。
+2. 明确角色的目标场景、可调用的 skills、不可越界的行为。
+3. 运行 `python3 scripts/lincoln_command_map.py --refresh` 生成 `lc-agent-<role>` 命令。
+4. 更新相关文档（`README.md`、`USAGE.md`、`.claude/workflows/README.md`）。
+
+## 如何新增 Skill
+
+1. 在 `.claude/skills/` 下创建目录或文件，包含 `SKILL.md` 与必要的 `prompts/`。
+2. 如果依赖外部 skill，在 `.claude/skills/dependencies.yaml` 中声明并 pin 到固定 ref。
+3. 运行 `python3 scripts/lincoln_command_map.py --refresh` 生成 `lc-skill-<name>` 命令。
+4. 在 `.claude/stages/` 中需要引用该 skill 的阶段里更新 `skills` 字段。
+5. 补充测试（如适用）和文档。
+
+## 如何新增 Harness 适配
+
+1. 在 `.claude/harnesses/` 创建 `<harness>.yaml` manifest。
+2. 在 `scripts/lincoln-setup.py` 中注册该 harness 的生成逻辑（如果现有逻辑不覆盖）。
+3. 运行 `python3 scripts/lincoln-setup.py generate-harness --harness <harness>`。
+4. 运行 `pytest tests/test_lincoln_harness_adapter.py` 验证生成产物。
+5. 确保新增 harness 默认关闭任何可能触发回退陷阱的能力（参考 codex `hooks: {}` 的处理）。
+6. 更新 `USAGE.md` 中的多 harness 支持说明。
+
+## 发布前验收
+
+每次发布前，对每个已生成适配的 harness 各跑一遍：
+
+| Harness | 一句话验收 |
+|---------|-----------|
+| Claude Code | 干净会话发「帮我开始一个新需求」 → 必须触发开场引导 / `lc-workflow-router`，并停在 clarify human_gate 前 |
+| codex | 干净会话发同一句话 → `AGENTS.md` 契约生效、`lc-*` prompts 可用，且没有任何 hooks 被自动激活 |
+| opencode | 干净会话发同一句话 → `.opencode/` 契约生效、`lc-*` 命令可用，且没有多余能力被默认开启 |
+
+任何一条不满足，不得发布。
+
+### 发布流程（维护者）
+
+1. 确保所有 PR 已合并，`main` 分支测试全绿。
+2. 运行 `python3 scripts/bump_version.py bump X.Y.Z`。
+3. 运行 `python3 scripts/bump_version.py --check` 验证 lockstep。
+4. 运行 `python3 scripts/package-lincoln-plugin.py check --check-dirty`。
+5. 运行 `python3 scripts/package-lincoln-plugin.py package` 生成 `dist/lincoln-X.Y.Z.tar.gz`。
+6. 创建 PR 合并 release 改动。
+7. 在 `main` 上打 tag `vX.Y.Z` 并推送（release tarball 标签）。
+8. 创建 GitHub Release 并上传 tarball。
+9. 发布/更新 npm 包：
+   - 打 `lincoln-vX.Y.Z` 标签触发 `.github/workflows/publish-lincoln.yml`，发布 `@sushanglewis/lincoln`。
+   - 旧 `lincoln-install` / `lincoln-update` npm 包保持已弃用状态，不再主动发布。
+
+### 从 vendored 模型迁移到全局插件模型
+
+v1.6.0 起 Lincoln 切换为 `npm install -g @sushanglewis/lincoln` 全局分发。迁移既有项目：
+
+1. 全局安装：`npm install -g @sushanglewis/lincoln && lincoln install --yes`
+2. 进入项目根目录，运行 `lincoln migrate-project --dry-run` 预览将被删除的框架文件。
+3. 确认后运行 `lincoln migrate-project --yes`：未修改的 vendored 框架文件会被删除，已修改/自定义文件保留，同时生成 `.lincoln.yaml`。
+4. 提交变更。之后项目的 `.claude/`、`scripts/` 等框架文件由全局 payload 提供，项目侧只保留 `.lincoln.yaml`、`.context/`、`issue-*/` 等本地状态。
+
+框架开发者若需要同时修改全局 payload，应在 Lincoln 仓库本身工作（该仓库通过自身的 `.lincoln.yaml` 保持自举）。
+
+## 获得帮助
+
+- 查看 [USAGE.md](USAGE.md) 了解 Lincoln 的使用方式。
+- 查看 [CLAUDE.md](CLAUDE.md) 了解 Agent 契约与产物规范。
+- 查看 [`.claude/workflows/README.md`](.claude/workflows/README.md) 了解工作流模板。
+- 在 GitHub Discussions 或 Issues 中提问。
+
+感谢你的贡献！

package/framework/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 苏尚lewis (sushanglewis)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/framework/README.en.md

@@ -0,0 +1,139 @@
+# Lincoln — AI-Native R&D Workflow & Product-Engineering Collaboration System
+
+> [中文](README.md) | English
+
+Lincoln is an AI-Native R&D workflow system spanning **IDEs, agent harnesses, code hosting, knowledge management, skills, plugins, and automation**. It runs on **stages** for rhythm, **gates** for quality, and **repeatable SOPs** as its backbone, chaining requirements clarification, product design, prototyping, TDD planning, OpenSpec proposals, task splitting, implementation, and knowledge-base distillation into one human-AI collaborative pipeline.
+
+- **Whole lifecycle, not a point tool**: every stage has explicit role, skill, and artifact contracts — agents step in at the right moments instead of replacing human judgment.
+- **Disciplined, not bureaucratic**: stage gates, human gates, branch hygiene, and the dual-track knowledge model keep collaboration traceable, handoff-ready, and auditable.
+- **Low-invasion and pluggable**: Lincoln blends into your project as a harness plugin — skills, hooks, workflow templates, and multi-harness adapters all extend along one meta-model.
+
+## Latest Release
+
+[![Release](https://img.shields.io/badge/release-v1.6.0-blue)](RELEASE.md)
+
+**v1.6.0** is released: Lincoln switches to a global npm plugin model. Install with `npm install -g @sushanglewis/lincoln`; projects opt in via `.lincoln.yaml`.
+
+See the full release notes in [RELEASE.md](RELEASE.md).
+
+## Quick Start
+
+Open the repo and tell the Agent what you want in plain language. Lincoln will route to the right workflow automatically:
+
+- **Start working on issue 55** → initializes the `issue-55` branch and work package, entering the `interview-to-knowledge` team workflow
+- **Use existing-project-iteration to understand this codebase** → scans source code, builds the `knowledge/` function library, and plans the next iteration
+- **Use design-spike to explore this idea** → clarifies requirements and produces a design review plus an interactive prototype
+- **What's the current status?** → reports current stage, blocker, recommended skills, and next action
+
+## Installation
+
+Lincoln is now distributed as a global npm plugin:
+
+```bash
+npm install -g @sushanglewis/lincoln
+lincoln install
+```
+
+`lincoln install` syncs the runtime framework to `~/.claude/`, `~/.codex/`, and `~/.opencode/`. Projects only need a `.lincoln.yaml` marker to opt in (empty directories won't activate Lincoln).
+
+The legacy `npx lincoln-install` / `npx lincoln-update` wrappers are still present but deprecated; migrate to the global CLI.
+
+First time? Read [USAGE.md](USAGE.md) for the full installation and usage guide.
+
+## What Lincoln Can Do
+
+### Stage-Driven Workflow Engine
+
+Each stage is defined in `.claude/stages/<stage-id>.yaml` with its role, skills, gates, and artifacts. The `workflow-stage.yaml` runtime state drives agent context injection, while Lincoln's stage loader handles stage validation, artifact recording, and gate advancement.
+
+### Preset SOP Workflow Templates
+
+| Workflow | Scenario | Mode |
+|----------|----------|------|
+| `interview-to-knowledge` | From interview recordings to GitHub Issues to Obsidian knowledge distillation | team |
+| `existing-project-iteration` | Existing source code: build knowledge first, then iterate | solo |
+| `bug-fix` | Clear bug: lightweight design, fast fix | solo |
+| `design-spike` | Requirements unclear: explore solutions and prototypes | solo |
+| `oss-first-design` | Heavily reliant on open-source solutions: research first, then design | solo |
+| `pm-research` | Systematic competitive/market/user/stakeholder research | solo |
+
+See [`.claude/workflows/README.md`](.claude/workflows/README.md) for the full template catalog.
+
+### Issue Work Packages (HTML Portal)
+
+Every requirement maps to one GitHub issue and one Lincoln feature branch. The `issue-<N>/` work package contains:
+
+- `index.html` — human-facing portal aggregating stage status, navigation, and artifacts
+- `workflow-stage.yaml` — machine-readable state and handoff protocol
+- `documents.yaml` — artifact index and human-approval status
+- `pages/docs/` — HTML pages for requirements, PRDs, designs, TDD plans
+- `pages/prototype/` — interactive HTML prototypes
+- `handoffs/` — stage handoff documents
+
+## Natural-Language Interaction
+
+Lincoln is AI-Native — **you don't need to type terminal commands**. Describe your intent in plain language and the Agent translates and executes the right scripts for you.
+
+| You say | Agent does |
+|---------|------------|
+| Start working on issue 55 | Initializes branch and work package, enters `interview-to-knowledge` |
+| What's the current status? | Reports current stage, blocker, and next action |
+| Record this stage's artifacts | Records artifacts and refreshes `documents.yaml` |
+| Confirm and proceed | Marks the current gate as approved after explicit human confirmation |
+| Generate handoff | Generates a handoff document |
+| Check the Lincoln environment | Detects dependencies and lists missing items |
+| List all active Lincoln branches | Lists stage status and blockers for every issue branch |
+| Run benchmark | Generates a Lincoln session benchmark report |
+| Start the PM research workflow | Enters the `pm-research` research chain |
+
+More commands and usage details are in [USAGE.md](USAGE.md).
+
+## Two Usage Modes
+
+### Lightweight Solo Path (vibe-coding / indie maker)
+
+Best for local projects and quick personal iteration. No GitHub issue required — just pick a workflow template and start. Artifacts land in the work-package directory, and you can upgrade to the team flow at any time.
+
+### Team Issue Path (product / design / engineering / QA)
+
+Every requirement uses a dedicated Lincoln feature branch named `issue-<N>`. Stage state travels with the branch; downstream roles check out the same branch and continue. Process documents stay on the feature branch and are **not merged to `main`** — only final code artifacts go through the PR.
+
+Detailed walkthroughs are in [USAGE.md](USAGE.md).
+
+## Tools
+
+- `@sushanglewis/lincoln` — global CLI: `lincoln install`, `lincoln update`, `lincoln use`, `lincoln doctor`, `lincoln init-project`, `lincoln migrate-project`, `lincoln record`
+- `tools/lincoln/` — Ink/React TUI for recording interviews (`lincoln-record` CLI)
+- `tools/lincoln-record/` — Rust local recording & transcription CLI (whisper-rs + Metal, speaker diarization)
+- `tools/lincoln-installer/` — legacy terminal TUI installer and updater (deprecated, kept for backward compatibility)
+
+## Multi-harness Support
+
+Lincoln's end-to-end logic — role contracts, stage workflows, and `lc-*` commands — can be derived for codex and opencode. `.claude/` is the single source of truth; harness artifacts are auto-generated by the adapter. **Never edit generated artifacts by hand.**
+
+Tell the Agent "generate codex adapter" or "generate opencode adapter". Generated artifacts are gitignored (`AGENTS.md`, `.codex-plugin/`, `.opencode/`). CI validates that manifests can be generated and that local artifacts have not drifted.
+
+## Extending and Contributing
+
+Lincoln's `.claude/` is an open system-prompt layer. Contributions of new agent roles, skills, hooks, or workflow templates are welcome.
+
+Before submitting a PR, please read:
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) — contributor guardrails, core vs. domain boundaries, test layers, and eval gates
+- [CLAUDE.md](CLAUDE.md) — agent contract, human-gate rules, and artifact conventions
+- [`.claude/workflows/README.md`](.claude/workflows/README.md) — steps for adding new workflow templates
+
+## Learn More
+
+- [USAGE.md](USAGE.md) — complete user manual
+- [CONTRIBUTING.md](CONTRIBUTING.md) — contributor guide
+- [RELEASE.md](RELEASE.md) — release notes and changelog
+- [`.claude/workflows/README.md`](.claude/workflows/README.md) — workflow template catalog
+- [OpenSpec docs](https://github.com/Fission-AI/openspec)
+- [Obsidian WikiLinks](https://help.obsidian.md/Linking+notes+and+files/Internal+links)
+
+## License
+
+Lincoln is released under the [MIT License](LICENSE), Copyright (c) 2026 苏尚lewis (sushanglewis).
+
+External skill, CLI, and plugin licenses are declared in [`.claude/skills/dependencies.yaml`](.claude/skills/dependencies.yaml) and [`.claude/agents/external/NOTICES.md`](.claude/agents/external/NOTICES.md).

package/framework/README.md

@@ -0,0 +1,139 @@
+# Lincoln — AI-Native 研发工作流与产研协作体系
+
+> 中文 | [English](README.en.md)
+
+Lincoln 是一个贯穿 **IDE、Agent Harness、代码托管、知识管理、技能、插件与自动化程序** 的 AI-Native 研发工作流体系。它以**阶段**为节奏、以**门控**为质量保障、以**可重复 SOP** 为骨架，把需求澄清、产品设计、原型、TDD 计划、OpenSpec 提案、任务拆分、研发实现和知识库沉淀串成一条可人机协作的流水线。
+
+- **全流程，而非单点工具**：每个阶段都有明确的角色、技能与产物约定——Agent 在恰当的节点介入，而不是替代人的判断。
+- **规范化，但不繁琐**：阶段门控、human gate、分支卫生，以及「过程文档留分支、耐用知识入 vault」的双轨机制，让协作可追溯、可交接、可审计。
+- **低侵入、可插拔**：以 harness 插件的形态融入你的项目——技能、hooks、工作流模板与多 harness 适配沿同一元模型扩展，不要求你为它改造自己的项目。
+
+## 最新版本
+
+[![Release](https://img.shields.io/badge/release-v1.6.0-blue)](RELEASE.md)
+
+**v1.6.0** 已发布：Lincoln 切换为全局 npm 插件模型，通过 `npm install -g @sushanglewis/lincoln` 安装，项目侧使用 `.lincoln.yaml` 选择性激活。
+
+查看完整发布说明：[RELEASE.md](RELEASE.md)
+
+## 快速开始
+
+打开仓库后，直接用自然语言告诉 Agent 你的目标即可。Lincoln 会自动进入对应的工作流：
+
+- **开始处理 issue 55** → 初始化 `issue-55` 分支与工作包，进入 `interview-to-knowledge` 团队工作流
+- **使用 existing-project-iteration 理解这个代码库** → 扫描源码并生成 `knowledge/` 功能知识库，再规划下一个迭代
+- **用 design-spike 探索这个想法** → 澄清需求并产出设计评审与可交互原型
+- **现在什么状态** → 汇报当前阶段、等待对象、推荐技能与下一步动作
+
+## 安装
+
+Lincoln 现在以全局 npm 插件的形式分发：
+
+```bash
+npm install -g @sushanglewis/lincoln
+lincoln install
+```
+
+`lincoln install` 会把运行时框架同步到 `~/.claude/`、`~/.codex/`、`~/.opencode/`。项目侧只需一个 `.lincoln.yaml` 标记即可选择性激活（空目录不会触发 Lincoln）。
+
+旧版 `npx lincoln-install` / `npx lincoln-update` 仍保留但已弃用，建议迁移到全局 CLI。
+
+第一次使用？阅读 [USAGE.md](USAGE.md) 获取完整安装与使用指南。
+
+## Lincoln 能做什么
+
+### 阶段驱动的工作流引擎
+
+每个阶段定义在 `.claude/stages/<stage-id>.yaml`，内含角色、可调用的技能、门控条件与产物要求。`workflow-stage.yaml` 作为运行时状态，由 Lincoln 的阶段加载器驱动阶段校验、产物记录与 gate 推进。
+
+### 预设 SOP 工作流模板
+
+| 工作流 | 场景 | 模式 |
+|--------|------|------|
+| `interview-to-knowledge` | 从访谈录音到 GitHub Issues 再到 Obsidian 知识库沉淀 | team |
+| `existing-project-iteration` | 已有源码，先建知识库再迭代 | solo |
+| `bug-fix` | 明确 bug，轻量设计后快速修复 | solo |
+| `design-spike` | 需求尚不清晰，做方案预研或原型 | solo |
+| `oss-first-design` | 强依赖开源方案，先调研再设计 | solo |
+| `pm-research` | 体系化完成竞品/市场/用户/相关者研究 | solo |
+
+完整模板说明见 [`.claude/workflows/README.md`](.claude/workflows/README.md)。
+
+### Issue 工作包（HTML 门户）
+
+每个需求对应一个 GitHub issue 和一个 Lincoln feature 分支。工作包目录 `issue-<N>/` 包含：
+
+- `index.html` — 人读门户，聚合阶段状态、导航与产物
+- `workflow-stage.yaml` — 机器状态与 handoff 协议
+- `documents.yaml` — 产物索引与 human 确认状态
+- `pages/docs/` — 需求、PRD、设计、TDD 计划等 HTML 页面
+- `pages/prototype/` — 可交互原型 HTML 页面
+- `handoffs/` — 阶段交接文档
+
+## 自然语言交互
+
+Lincoln 是 AI-Native 工作流——**你不需要在终端输入任何命令**。直接用自然语言描述意图，Agent 会自动翻译成对应脚本并代为执行。
+
+| 你说 | Agent 做 |
+|------|----------|
+| 开始处理 issue 55 | 初始化分支与工作包，进入 `interview-to-knowledge` |
+| 现在什么状态 | 汇报当前阶段、等待对象与下一步 |
+| 提交本阶段产物 | 记录产物并刷新 `documents.yaml` |
+| 确认通过 | 在人类 PM 显式确认后标记 gate 通过 |
+| 生成交接 | 生成 handoff 文档 |
+| 检查 Lincoln 环境 | 检测依赖并列出缺失项 |
+| 列出所有活跃分支 | 列出所有 issue 分支的阶段状态与等待对象 |
+| 运行 benchmark | 生成 Lincoln 会话基准评测报告 |
+| 启动 PM 研究工作流 | 进入 `pm-research` 研究链路 |
+
+更多命令与用法见 [USAGE.md](USAGE.md)。
+
+## 两种使用方式
+
+### 轻量个人路径（vibe-coding / 独立 maker）
+
+适合本地项目、个人想法快速迭代。无需先建 GitHub issue，直接选择 workflow 模板即可开始。产物落在工作包目录下，可随时升级为团队流程。
+
+### 团队 issue 路径（产品 / 设计 / 研发 / QA）
+
+每个需求使用独立的 Lincoln feature 分支（命名约定 `issue-<N>`）。阶段状态随分支提交，下游角色 checkout 同一分支继续。过程文档不合并到 `main`，通过 PR 只合并最终代码产物。
+
+详细路径说明见 [USAGE.md](USAGE.md)。
+
+## 工具
+
+- `@sushanglewis/lincoln` — 全局 CLI：`lincoln install`、`lincoln update`、`lincoln use`、`lincoln doctor`、`lincoln init-project`、`lincoln migrate-project`、`lincoln record`
+- `tools/lincoln/` — 基于 Ink/React 的 TUI 录音前端（`lincoln-record` CLI）
+- `tools/lincoln-record/` — Rust 本地录音转写 CLI（whisper-rs + Metal 加速、说话人分离）
+- `tools/lincoln-installer/` — 旧版终端 TUI 安装器与更新器（已弃用，保留向后兼容）
+
+## 多 harness 支持（codex / opencode）
+
+Lincoln 的端到端逻辑（角色契约、阶段工作流、`lc-*` 命令）可适配到 codex 与 opencode。`.claude/` 是唯一事实源，各 harness 产物由适配器自动生成，**不要手改生成产物**。
+
+需要对 Agent 说「生成 codex 适配」或「生成 opencode 适配」。生成产物不入 git，CI 会校验 manifest 可生成、本地产物未漂移。
+
+## 扩展与贡献
+
+Lincoln 的 `.claude/` 是开放的系统提示层，欢迎基于同一套元模型贡献新的 Agent 角色、skills、hooks 或工作流模板。
+
+提交 PR 前请阅读：
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) — 贡献者护栏、核心与领域包边界、测试分层与 eval 门禁规范
+- [CLAUDE.md](CLAUDE.md) — Agent 契约、人类门控规则与产物规范
+- [`.claude/workflows/README.md`](.claude/workflows/README.md) — 新增工作流模板的步骤
+
+## 了解更多
+
+- [USAGE.md](USAGE.md) — 完整用户手册
+- [CONTRIBUTING.md](CONTRIBUTING.md) — 贡献者指南
+- [RELEASE.md](RELEASE.md) — 发布说明与 Changelog
+- [`.claude/workflows/README.md`](.claude/workflows/README.md) — 工作流模板总览
+- [OpenSpec 文档](https://github.com/Fission-AI/openspec)
+- [Obsidian WikiLinks](https://help.obsidian.md/Linking+notes+and+files/Internal+links)
+
+## License
+
+Lincoln 本体以 [MIT License](LICENSE) 发布，Copyright (c) 2026 苏尚lewis (sushanglewis)。
+
+外部 skills、CLI 与插件的许可证声明见 [`.claude/skills/dependencies.yaml`](.claude/skills/dependencies.yaml) 与 [`.claude/agents/external/NOTICES.md`](.claude/agents/external/NOTICES.md)。