# Finish Project

> |-

- **Type:** Skill
- **Install:** `agentstack add skill-xurb-nexus-nexus-harness-finish-project`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [xurb-nexus](https://agentstack.voostack.com/s/xurb-nexus)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [xurb-nexus](https://github.com/xurb-nexus)
- **Source:** https://github.com/xurb-nexus/nexus-harness/tree/main/skills/finish-project
- **Website:** https://xurb-nexus.github.io/nexus-harness/

## Install

```sh
agentstack add skill-xurb-nexus-nexus-harness-finish-project
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Finish Project —— 项目收尾：回写 → 归档

> **框架不可变铁律**（复用自 [`AGENTS.md`](../../AGENTS.md) 第 7 条）  
> 本 SKILL.md 及其 `scripts/` / `tests/` 等框架文件在"使用本 skill"过程中**只读**。  
> 发现 bug 必须立刻停下，向用户报告，由用户决定是否开新会话修。  
> 唯一豁免：用户在当前会话明确声明"现在就是来改这个 skill 的"。

> **Finish Git 铁律**  
> `finish-project` 全流程禁止执行 `git push`。  
> 禁止自动 merge `dev` / `master` / `main` 分支，禁止生成或执行把需求分支合入这些主干分支的命令。  
> 如需上线合并，只能在收尾报告中提示“请人工按团队流程处理”，不得由本 skill 代办。

## 职责边界

`finish-project` 只做项目完结收口：

1. 审计 `workspace//` 的 PRD/TRD/Plan/STATUS/TDD/Review 证据。
2. **AIWeave 整合后（仅 Go 项目，`aiweave_status in {T1, T2}`）**：
   - 跑最终 `/sync-feature-to-docs`（vendor skill）：输入 = git diff（项目分支 vs main）+ TRD `docs_increment_plan` + `context.json.pending_docs_sync_notes`（developer 阶段累计的任务 `build_status_module_path` / `build_status_target`）+ vendor 模板路径；主 Agent 按 vendor `templates/skills/sync-feature-to-docs/SKILL.md` 执行；反向同步 docs/、**新增所有 developer 阶段新建模块的 ⬜ 行并翻 🟢**、更新 INDEX。这是 TRD bootstrap 之后唯一合法的 `docs/BUILD_STATUS.md` 写入窗口。产物 `/finish_aiweave_sync_report.md`。
   - 跑 `/doc-sync-check all` 兜底：无 blocking 才继续；有 blocking → 写入 FINISH_REPORT 并停下。
   - 派发 `finish-project-reviewer` **评审目标改为 docs/ 同步 diff**（不再走 KB 回写候选评审）。
3. 把一次性项目产物移动到 `archive//`。
4. 把 `*.review_report.json`、`*.hard_check_report.json`、`*.dev_review_report.json`、`finish_aiweave_sync_report.md` 移入 `review-history/`。
5. 生成 `FINISH_REPORT.md` 留痕，新增「AIWeave 同步状态」段：本次同步 docs/ 文件清单、BUILD_STATUS 变更、未通过 doc-sync-check 项。
6. 生成本地任务分支清理计划，并在用户明确确认时只删除安全的本地任务分支。

> **强制归档场景（用户选「跳过 AIWeave 同步」）**：FINISH_REPORT 显著标红「AIWeave docs/ 未同步，下次需先手工补齐」；`context.json` 写 `aiweave_sync_skipped=true`。

> **断开旧 KB 回写**：旧版"KB 回写候选 + 用户三选一"流程已废弃。原 `collect_kb_candidates / dispatch_kb_reviewer / apply_kb_writeback / auto_converge_kb_candidates` 调用节点不再触发；脚本残留路径保持向后兼容旧 archive 但**不在新流程中走通**。

**不做**：
- 不自动 commit / push，尤其禁止 `git push`。
- 不自动 merge `dev` / `master` / `main`。
- 不自动删除远端分支。
- 不删除需求总分支、当前分支、`dev` / `master` / `main` / `docker`。
- 不移动 `knowledge/` 目录本身。
- 不替用户确认 KB 回写项。

---

## 标准流程

入口来源可以是启动页 `4`、自然语言“归档项目 / 项目收尾 / finish project”、developer 完成后的衔接，或 `继续项目` / `下一步` 识别出的 `finish_ready`。无论从哪里进入，后续都由本状态机统一接管项目选择、收尾审计、KB 回写确认和归档确认。

### Step 1 · 选择项目

运行：

```bash
python3 skills/finish-project/scripts/finish_wizard.py
```

状态机返回 `action="ask_user"` 时，把 `presentation.question` 原文给用户，等待用户回复编号。禁止在入口层自行扫描并包装项目状态。

**全局返回入口词（与 `AGENTS.md` 一致）**：用户本条输入**仅为** `nexus` 或 `Agent`（单独一行；大小写不敏感）时，**不得**视为无效选项、**不得**要求用户「请重新回复 1」；主 Agent 立即退出 `finish-project` 追问，重新展示 1–6 启动入口，**不**把该字符串传入 `finish_wizard.py` 的 `selection` / `confirm_text` 等参数。用户在新入口重新选流程后，再按路由进入对应 skill。

### Step 2 · 收尾审计

用户选择项目后调用：

```bash
python3 skills/finish-project/scripts/finish_wizard.py \
  --params-json '{"selection":""}'
```

状态机审计：
- `context.json` 是否存在。
- `prd_path` / `trd_path` / `plan_dir` 是否存在。
- `plans/**/STATUS.md` 任务是否全部 completed。
- `TDD Audit` 是否全部 red / green / refactor 为 true。
- 阻塞项是否清空。
- review 报告数量。

收尾确认菜单遵循**单一选项原则**（2026-05-11 起）：所有状态都只展示 1 个正向选项，下面再用一句话提示"不想现在归档，请结束会话。"。**不再展示 cancel 编号选项**——cancel 等价于"用户什么都不做就退出"，用自然语言/直接结束会话表达即可；保留显式 cancel 反而误导用户以为另有别的归档路径。

| 项目状态 | 唯一选项 | Agent 翻译契约 |
|---|---|---|
| `can_finish=true`（无阻塞） | `1. 确认归档` | 用户回复 1 → `confirmed=true` 再调；**全局词** `nexus` / `Agent`（单独一行）→ 退出本 skill 并展示入口；用户表达不想归档（或回复其他非全局词内容） → 直接结束本次 finish 会话，不再调脚本 |
| `can_finish=false`（有阻塞） | `1. 强制归档`（带未完成项归档，FINISH_REPORT 中注明） | 用户回复 1 → `confirm_text="强制确认"`（明确授权强制归档，等价 `force=True`）；**全局词** `nexus` / `Agent`（单独一行）→ 退出本 skill 并展示入口；其余非全局词 → 结束会话 |
| 仅缺人工确认（pending_confirm 场景 A） | `1. 确认归档`（系统自动补登 ✅ completed） | 同 can_finish=true |
| 真未完成项 + 缺人工确认（pending_confirm 场景 B） | `1. 强制归档` | 同 can_finish=false |

底层 `archive_project.py` 仍执行硬闸：未完成项目调用必须带 `--force --force-confirm 强制确认`，否则拒绝移动目录。Agent 拿到 wizard 返回的 `execution_plan` 后调 `archive_project.py` 时，若该项目 `can_finish=false`，必须显式补 `--force --force-confirm 强制确认`。

### Step 3 · 生成 KB 回写候选并批量质检

确认进入收尾后，状态机会执行：

```bash
python3 skills/finish-project/scripts/collect_kb_candidates.py \
  --workspace-path 
```

候选只能从当前项目的 TRD 与 Plan 中提取；不得从 PRD、review 报告、历史聊天或 Agent 自己总结中凑候选。候选按 TRD/Plan 知识点生成，每个 `Cxxx` 是一个已通过初筛、值得让用户判断是否回写的知识单元，而不是一句简单摘要或原始候选。状态机会对每个知识点遍历 `context.json.knowledge_base_dirs` / `kb_paths` 中的所有依赖 KB，并为每个 KB 给出 `append_targets` / `kb_evaluations`：

| 目标文件 | 候选来源 |
|---|---|
| `01-architecture.md` | 业务目标、范围、系统边界、版本关系、权限/中间件、主链路不变性 |
| `02-database.md` | MySQL/ES 表结构、字段、索引、Redis Key 模板本体、存储模型 |
| `03-api.md` | HTTP Path、请求字段、响应字段、错误码、接口协议、字段来源 |
| `04-business-logic.md` | 列表/创建/提交/排行等业务流程、状态流转、清理/结算链路 |
| `05-dependencies.md` | 配置中心、Redis/MQ/ES/HTTP 下游、缓存 TTL、资源读写边界、账期依赖 |
| `06-code-conventions.md` | 常量命名、目录约定、测试约束、实现规范、迁移注意事项 |

候选生成、`finish-project-reviewer` 和本地 hard gate 必须共用同一套 TRD/Plan 语义映射规则。禁止候选生成用一套关键词、reviewer 再用另一套口径，导致类似“业务目标写入 `03-api.md`”“配置中心/Redis 依赖写入架构章”这类前后漂移。当前共享规则落在 `skills/finish-project/scripts/kb_writeback_mapping.py`，主要约束是：

- “业务目标 / 范围 / 系统边界 / 版本关系 / 权限中间件 / 主链路不变性”默认归 `01-architecture.md`；若同一段明确描述配置中心、Redis、MQ、ES、下游或读写边界，则资源事实优先归 `05-dependencies.md`。
- “HTTP Path / 请求响应字段 / 错误码 / 接口协议”才归 `03-api.md`；不能因为文本里出现“路由”“请求”就把业务目标或依赖策略写入接口章。
- 建议追加正文必须是稳定 KB 差量正文，不能直接复制 TRD 原段；hard gate 对原文照搬、过长正文、`reviewer` 流水、`候选 Cxxx`、截断尾句执行 major 拦截并给出 rewrite。

候选生成后，**不得直接展示给用户**。必须先批量派发 reviewer：

```bash
python3 skills/finish-project/scripts/dispatch_kb_reviewer.py \
  --workspace-path  \
  --candidates-path /finish_kb_candidates.raw.json \
  --round 1
```

宿主有 subagent 能力时，必须使用派发包里的 `task_prompt_template` 启动独立上下文 `finish-project-reviewer`。Cursor 可用 `generalPurpose + task_prompt_template`，仍算真 sub-agent；Claude Code / OpenCode 使用注册的 `finish-project-reviewer`。

#### reviewer 派发不可停规则（对齐 developer）

收到 `finish_wizard.py` 返回 `action="dispatch_reviewer"` 后，这是主 Agent 的**内部下一步**，不是给用户看的阶段性结果：

- Cursor 中必须立即调用 `Subagent(subagent_type="generalPurpose", prompt=task_prompt_template)`，默认同步等待完成；禁止主动后台派发来换取提前回复。
- reviewer 未落盘期间，禁止输出“请等 Agent 跑完 / 看到 JSON 后告诉我 / 回到本会话发 reviewer 好了”等用户操作项。
- reviewer 完成后，主 Agent 必须读取 `reviewer_output_path`，确认 JSON 合法、`dispatch_id` 匹配，再把 `candidates_path`、`reviewer_report_path`、`review_round` 回传 `finish_wizard.py`。
- reviewer 报告通过后，`finish_wizard.py` 会生成 `finish_kb_candidates.reviewed.json` 并进入逐项 `Cxxx` 展示。
- reviewer 报告有 blocking/major 时，主 Agent 必须按报告修复候选并重派，最多 3 轮；禁止让用户手工执行 repair / redispatch。
- 只有 Subagent 工具不可用、报告未落盘且重派仍失败、或修复需要业务判断时，才允许停下给用户选项。

最终回复前可运行：

```bash
python3 skills/finish-project/scripts/finish_flow_guard.py \
  --wizard-result-path 
```

`can_stop=false` 时禁止向用户收口，必须按 `required_action` 继续内部流程。

reviewer 一次性审完整批候选 `C001-C00N`，而不是每个候选派一次。若 reviewer 报告有 `blocking` / `major`，主 Agent 先用报告修复候选，再重新派发 reviewer；最多 3 轮。最终：

- reviewer 通过：只展示通过版本。
- 修完后条目数可能不变，也可能从 15 条变成 10 条。
- 连续 3 轮仍未清理干净：停止自动循环，把当前候选和 reviewer 未解决问题一起交给用户选择。

回流硬门禁：
- reviewer 返回后，不管 `approved=true/false`，主 Agent 都必须先把 `candidate_decisions` 应用到候选，完成 remove / retarget / rewrite / drop。
- 应用后必须运行本地 hard gate（`run_kb_candidate_review.py` 同等规则）兜底检查错误 KB、错误章节、整段 TRD 原文、过程编号、重复追加正文。
- 只有 reviewer approved 且 hard gate 无 blocking/major，才允许写出 `finish_kb_candidates.reviewed.json` 并展示给用户。
- reviewer approved 但 hard gate 发现 major，仍必须先自动修复并重派 reviewer；禁止把“用户逐条择优选择”作为质量问题的替代修复。

无 subagent 能力的宿主才可降级运行：

```bash
python3 skills/finish-project/scripts/auto_converge_kb_candidates.py \
  --workspace-path  \
  --max-rounds 3
```

降级模式必须在汇报中标明；它只能作为机械兜底，不替代语义 reviewer。

向用户展示候选项时必须逐项推进，默认不写回，禁止先展示完整候选大表后让用户批量选择，禁止只给“跳过 / 写指定编号 / 写全部”的粗菜单后让用户自行判断。允许在第 1 条前展示一个轻量“候选概览”（总数 + Cxxx 标题 + 推荐目标），但概览只用于让用户知道全貌，不能提供批量写回选项；随后必须立即进入 `C001` 的详细确认。

`collect_kb_candidates.py` 只有在知识点通过以下初筛后，才允许分配 `Cxxx` 编号：
- 不是 TRD 过程信息、文档执行约束、guard/lint 规则、模板字段补齐等噪音。
- 至少命中一个依赖 KB 的合法章节，并存在推荐追加目标。
- 具备以下价值之一：新增事实、修正旧事实、补齐缺失细节、提升可开发性、沉淀跨项目复用经验、既有系统再梳理价值。
- 即使本次代码未实现，只要内容基于现有代码 / 现有 KB / TRD+Plan 对既有系统的详细梳理，且比 KB 更可开发，也可进入候选；但必须标明实现状态与可信度来源。

每个 `Cxxx` 至少展示：
- TRD/Plan 原文摘录（`trd_excerpt` / `content`）。
- 来源文件与来源类型（TRD / Plan）。
- 实现状态：已实现需说明代码证据；未验证或强制归档时标注“未验证 / 仅来自 TRD 或 Plan”。
- 为什么值得回写（`worthiness.reason`）、价值类型（`worthiness.value_type`）与命中的价值信号。
- 对每个依赖 KB 的判断：目标 KB、目标章节、建议动作、理由。
- 建议追加文本。
- 建议追加文本必须是最终将写入 KB 的正文；不得包含 `候选 Cxxx`、reviewer 轮次、dispatch id、`reviewer_output_path` 等过程信息。

标准交互是一次只展示一个 `Cxxx`：
1. 若当前是第 1 条，可先展示轻量候选概览：共有 N 条、每条标题、推荐写入目标数或目标章节。
2. 来源确认：说明来自 TRD 还是 Plan，展示来源文件。
3. 内容摘录：展示 TRD/Plan 原文摘录。
4. 原因说明：说明为什么值得回写。
5. 目标确认：列出只来自 `append_targets` 的目标 KB/章节；非 append 的 KB 只能作为“不建议写入”原因。
6. 用户选择：`1. 同意回写` / `2. 不回写，继续下一条` / `3. 暂停`。
7. 处理完当前 `Cxxx` 后，才展示下一个 `Cxxx`。

展示层硬约束：
- 只能展示脚本返回的 `append_targets` 作为可写入目标；禁止根据 `knowledge_base_dirs` 手工合成 `C001-K01 / C001-K02`。
- `kb_evaluations` 中 `action != "append"` 的目标只能展示为跳过原因，不能出现在“默认追加 / 推荐追加”里。
- 若某个 `Cxxx` 的 `append_targets` 为空，不得展示给用户确认，必须跳过该候选并继续下一个。
- 候选总览里的“主目标”必须来自 `append_targets`，不得写成“两 KB 同路径各一份”这类概括。
- 展示层必须清理目标理由里的跨域脏标签：如果最终只写某个 KB，理由不得保留其他非目标领域的标签。r 修复流水（如多段“reviewer 修正 / reviewer 改写追加正文”）原样暴露给用户；目标确认必须拆成“目标 KB / 目标章节 / 推荐理由 / 建议追加正文”四段，推荐理由只保留用户决策需要的信息。
- 建议追加正文不得以半句结尾（如“主从延迟下”“考虑”“避免”“按”等截断尾巴）；hard gate 必须拦截并重写。

用户确认粒度：
- 回复 `C001`：写入该知识点下所有推荐 `append_targets`。
- 回复 `C001-K02`：只写入该知识点的某个目标 KB。
- 回复“跳过 C001”：不得写回该知识点。
- 用户要求修改追加文本时，先按用户意见修改候选内容，再写回。

强制归档场景下，长期 KB 只应写入用户明确确认的项；未确认或未实现项可以记录到 `FINISH_REPORT.md`，不得默认写入 `knowledge/`。

### Step 4 · 写回 KB

用户确认候选后运行：

```bash
python3 skills/finish-project/scripts/apply_kb_writeback.py \
  --workspace-path  \
  --candidates-json  \
  --confirmed-ids C001,C003-K02
```

写回前自动备份被修改 KB 文件到 `.backup/finish-project//...`。
写回脚本只允许目标位于本仓库 `knowledge/` 下，且文件名必须属于 `00-index.md` ~ `06-code-conventions.md`。
写回方式统一为追加式回写，不直接改写原有段落。

若用户选择“跳过 KB 回写”，不得写 `knowledge/`。

### Step 5 · 归档项目

运行：

```bash
python3 skills/finish-project/scripts/archive_project.py \
  --workspace-path 
```

归档规则：
- `workspace//` → `archive//`
- review / hard_check / dev_review 报告 → `archive//review-history/`
- 归档目录生成 `FINISH_REPORT.md`
- `workspace-path` 必须是本仓库 `workspace//`，防止误移动任意目录

未完成项目如需强制归档，必须使用：

```bash
python3 skills/finish-project/scripts/archive_project.py \
  --workspace-path  \
  --force \
  --force-confirm 强制确认
```

### Step 6 · 分支清理（交互式，由 finish_wizard 内建）

分支清理现在在归档执行前由 `finish_wizard.py` 交互式完成，**无需手动运行脚本**。

**触发时机**：`finish_wizard.py` 在返回 `action=execute` 之前，会自动检测业务仓库中的本地任务分支，若存在可安全删除的分支，则返回 `stage=branch_cleanup_ask` 向用户提问：

```
找到 N 个可安全删除的本地任务分支（已 completed 且已合入 ）：
- `feature/my-module-t01`（T01，...）
- `feature/my-module-t02`（T02，...）
...
注：需求总分支 `feature/my-module` 及 master/main/dev 等受保护分支不会被清理。

请选择：
1. 自动清理（删除以上任务分支）
2. 手动清理（自行处理后回复「我已清理」）
3. 跳过（保留所有分支不动）
```

**处理规则**：
- 用户选 `1`（自动清理）→ `branch_cleanup_choice=auto`，wizard 立即执行删除，结果写入 `execution_plan.branch_cleanup.deleted`；
- 用户选 `2`（手动清理）→ 等用户回复「我已清理」后 `branch_cleanup_choice=manual`，不执行任何 git 操作，继续归档；
- 用户选 `3`（跳过）→ `branch_cleanup_choice=skip`，直接进入归档。

**安全约束**：
- 只删 `safe_to_delete`（matched `-tNN`，已 completed 且已合入总分支的本地任务分支）；
- 需求总分支、基础分支、`master / main / dev / docker` 永远不删；
- 不 push，不删远端分支，不 merge 到 `dev / master / main`；
- **若待删任务分支恰好是当前 checkout 分支**（最后任务收尾后的常见状态），`branch_cleanup_plan.py` 会标 `requires_checkout_switch=True`，并在执行删除前自动 `git checkout ` 再删；删除完成后保持在集成分支上。**前提是工作区干净**：若有未提交改动，会拒绝切换并把该分支放进 `skipped_delete`，等用户先 commit / 丢弃后重试。

归档完成后，`FINISH_REPORT.md` 中的分支清理区块会反映清理结果（已删 / 保留 / 跳过）。

---

## 输出规范：决策点 Tips 追加

**所有向用户展示含编号选项（`1. / 2. / 3.`）的消息，必须在选项列表末尾追加以下内容（禁止省略）**：

```
---
💡 迷路了？输入「下一步」继续
```

适用场景：项目选择、KB 候选确认、归档确认、分支清理询问等所有带编号选项的节点。

---

## 交付格式

完成后简短汇报：

```text
项目已归档：archive/

Review 历史：review-history/
收尾报告：archive//FINISH_REPORT.md
```

分支清理已在归档前通过 `finish_wizard.py` 交互式完成（见 Step 6），归档结束后无需再询问。

### 收尾换会话引导（归档完成后必须追加，禁止省略）

归档汇报是整条 finish 流程里上下文最满、用户又「不知道下一步」的节点。因此在上面汇报的**正下方**必须**原样**追加这一行（finish 不再依赖 Stop hook 上下文报警，无论上下文是否真满都给）：

```text
本项目已归档完成。如需继续其它工作，请先 `/clear`，再输入 `nexus` 回到启动入口。
```

注意：这里是「项目已结束 → 回入口」，别用 developer 那套「`/clear` 后选 `2. 继续进行中的项目`」。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [xurb-nexus](https://github.com/xurb-nexus)
- **Source:** [xurb-nexus/nexus-harness](https://github.com/xurb-nexus/nexus-harness)
- **License:** Apache-2.0
- **Homepage:** https://xurb-nexus.github.io/nexus-harness/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-xurb-nexus-nexus-harness-finish-project
- Seller: https://agentstack.voostack.com/s/xurb-nexus
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.