Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions plugins/waypoint/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),

## [Unreleased]

### Added

- `project-navigator`: a precheck before the order review. A new read-only subagent `waypoint:navigator-checker`, dispatched with the output of the new `precheck-brief` command, checks each fact written in the work order (file paths, ids in the data, the release form and license of external resources) and whether each criterion can be verified. The orchestrator fixes the order and runs the new `order precheck`; until then `reply approve` and `order set issued` refuse a drafting order. In a real project every blocked round of the implementation orders came from an unchecked fact in the order.
- `project-navigator`: pending criteria. When only a few criteria cannot be met as written, the executor finishes the rest and lists them under the new "待定判据" (pending criteria) item of the receipt instead of ending as blocked; the reviewer marks them unverified, and the user decides in the review report.
- `project-navigator`: a new reply "等待操作" (waiting for your action, no option block). When the executor only needs the user to do something by hand, it hands back midway without writing a receipt, and continues after the user replies; the order status does not change. Before, each such step was a full blocked round trip.
- `project-navigator`: subagent models. The new `model` command shows the assignment and `model set <role> <model> [--kind <order kind>]` changes it; the "next action" and a new "子代理模型" (subagent models) line of `status` spell out the `model` parameter to pass when dispatching.

### Changed

- `project-navigator`: the checker, reviewer, reader, and researcher subagents now run on Sonnet by default; the executor still follows the orchestrator's model. Run `project-navigator model set <role> inherit` to restore the earlier behavior for a role.
- `project-navigator`: a drafting order written before this version needs `order precheck` once before it can be reviewed.

## [1.3.2] - 2026-11-12

### Fixed
Expand Down
25 changes: 25 additions & 0 deletions plugins/waypoint/agents/navigator-checker.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
---
name: navigator-checker
description: project-navigator 的核对子代理, 只由编排会话按 precheck-brief 生成的提示词派出, 在工单发布之前逐条核对其中写下的事实. Pre-issue fact checker for project-navigator; dispatched only by the orchestrator session with the generated precheck brief. Do not use for anything else.
disallowedTools: Write, Edit, MultiEdit, NotebookEdit
---

你是 project-navigator 的核对子代理, 在全新的上下文中核对一张还没有发布的工单: 其中写下的事实是否成立, 判据能否验证.

## 立场

- 只读: 不写, 不改, 不删任何文件, 也不尝试这样做. 不安装依赖, 不改动项目.
- 只报告事实与证据, 不改写工单, 不给实现方案, 不评价工单写得好不好.
- 委派提示词中的 "核对要求" 与 "交回格式" 是唯一的任务说明, 逐条完成, 不增不减.

## 取证

- 每条结论都附证据: 文件路径与行号, 命令的原样输出, 或网页地址与摘录. 不凭记忆下结论.
- 只运行只读命令: 读文件, 搜索, 只读 git 命令, 以及查询数据的命令 (例如对项目数据文件的只读查询). 不运行构建, 测试与会写文件的脚本.
- 外部资源 (下载地址, 发布形式, 许可) 用网络工具查看原始页面.
- 结论只用委派提示词列出的几种. 查不到证据时写 "无法核对", 并写明缺少什么; 不凭推测写 "成立".

## 交回

- 按委派提示词的 "交回格式" 输出, 用简体中文.
- 标点使用英文 (ASCII) 标点, 每个标点后加一个空格; 标点属于路径, 版本号等记号时不加.
129 changes: 78 additions & 51 deletions plugins/waypoint/docs/project-navigator-maintaining.en.md

Large diffs are not rendered by default.

129 changes: 78 additions & 51 deletions plugins/waypoint/docs/project-navigator-maintaining.md

Large diffs are not rendered by default.

58 changes: 42 additions & 16 deletions plugins/waypoint/docs/project-navigator.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ Take "build a tool that collects the team's weekly reports" as an example, start
2. The skill may recommend technologies from the research; key dependencies such as the language, framework, and core libraries are verified with selection work orders.
3. When a work order is written, the skill replies with "工单审阅" (work order review): the goal in one sentence, the decisions it needs from you, what is out of scope, and why the order has this size. Answer `A` if it is right, or `B` with the changes you want. The full order is at the path shown under the review points.
4. After you answer `A`, the skill dispatches an executor subagent in the background and replies with "工单执行" (order running). You can do something else; the orchestrator continues on its own when the executor finishes.
5. When the executor is blocked (for example, it needs an account from you, or a choice between approaches), the skill replies with "受阻处理" (blocked handling) for you to decide; the executor then continues.
5. When the executor is blocked (for example, the specification contradicts itself, or it needs a choice between approaches), the skill replies with "受阻处理" (blocked handling) for you to decide; the executor then continues. When it only needs you to do something by hand, the skill replies with "等待操作" (waiting for your action), and you reply "操作完成" (done) afterwards.
6. When the work is done, the skill sends the reviewer subagent and replies with "验收报告" (review report). If everything passes, choose `A` to commit, `B` to commit and push, or `C` if you found a problem. For a selection order, you decide whether to adopt the result or choose another option.

The skeleton and every later slice follow the same work order round trip. Normally a work order needs two decisions from you: publish it at review, and accept and commit it after the review.
Expand Down Expand Up @@ -97,15 +97,39 @@ All records are kept. The upgrade is committed through commit-message.

## Roles

| Role | Who | What it does |
| ----------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| Orchestrator | The session that invokes the skill | Plans, records, writes work orders, organizes reviews and checkups; writes only `.navigator/` |
| Executor subagent | Dispatched by the orchestrator in the background | Writes code, tests, and the receipt for one work order; never commits or pushes |
| Reviewer subagent | Sent by the orchestrator, with a fresh context | Checks each criterion, runs the code checks and tests, returns evidence; read-only |
| Research subagent | Sent by the orchestrator during framing | Researches the problem domain: similar products, users, practice, constraints; read-only |
| You | The only decision maker | Every decision: publishing orders, handling blocks, accepting reviews, how to commit |
| Role | Who | What it does |
| ----------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Orchestrator | The session that invokes the skill | Plans, records, writes work orders, organizes reviews and checkups; writes only `.navigator/` |
| Checker subagent | Sent by the orchestrator before the order review | Checks that each fact written in the order holds and each criterion can be verified; read-only |
| Executor subagent | Dispatched by the orchestrator in the background | Writes code, tests, and the receipt for one work order; never commits or pushes |
| Reviewer subagent | Sent by the orchestrator, with a fresh context | Checks each criterion, runs the code checks and tests, returns evidence; read-only |
| Research subagent | Sent by the orchestrator during framing | Researches the problem domain: similar products, users, practice, constraints; read-only |
| You | The only decision maker | Every decision: publishing orders, handling blocks, accepting reviews, how to commit |

The hooks guard only a few boundaries: the orchestrator cannot write files outside `.navigator/`; the state file and the generated views can only be changed by plugin commands; under `.navigator/` the executor can write only its order's receipt and evidence files, and on run-check and analysis orders it cannot change business files; the reviewer cannot write files. Everything else is left to the skill's rules and is not blocked.
The hooks guard only a few boundaries: the orchestrator cannot write files outside `.navigator/`; the state file and the generated views can only be changed by plugin commands; under `.navigator/` the executor can write only its order's receipt and evidence files, and on run-check and analysis orders it cannot change business files; the checker and the reviewer cannot write files. Everything else is left to the skill's rules and is not blocked.

### Which model each subagent uses

The model of a subagent is set when it is dispatched. The defaults are below; `project-navigator model` shows the current assignment:

| Subagent | Default model | Why |
| ------------------------------------- | ------------------------ | ---------------------------------------------------------------------------- |
| Executor | Follows the orchestrator | It designs and decides, and it is the one that points out a wrong work order |
| Checker, reviewer, reader, researcher | Sonnet | They gather evidence against a list and need no design judgement |

To change it, tell the orchestrator or run the command yourself. A model is `sonnet`, `opus`, `haiku`, `fable`, or `inherit` (follow the orchestrator):

```bash
project-navigator model set reviewer inherit
```

The executor can be set per order kind, for example Sonnet for fix orders only:

```bash
project-navigator model set executor sonnet --kind fix
```

Before moving implementation orders to a smaller model, look at how often recent orders were blocked or rejected: one round of rework makes the orchestrator read the receipt again, change the order, and dispatch again, which can cancel the saving.

### Permission prompts

Expand All @@ -127,14 +151,16 @@ A requirement change can be inserted at any stage, and the work returns to where

## One work order round trip

1. **Review.** The orchestrator writes the work order and replies with "工单审阅" (work order review), listing only the review points and the order file path. The order can be issued only after you choose A; if the order changes after that, it is reviewed again.
2. **Execution.** The orchestrator dispatches an executor subagent in the background and replies with "工单执行" (order running). The executor checks the commit and assumptions, plans, implements, checks itself, and writes the receipt. "工单执行" needs no choice from you, so it has no option block; to stop and change the order midway, reply "停止执行" (stop).
3. **Blocked.** When the executor hits a specification problem, or needs an action or decision from you, it explains in the receipt and stops. The orchestrator replies with "受阻处理" (blocked handling); once you have handled it and the order does not need to change, the same executor continues without a new review.
4. **Review of the work.** The orchestrator sends the reviewer subagent to check each criterion; the only verdicts are pass, fail, and unverified. While the reviewer works in the background, the orchestrator first replies with "工单验收" (order under review, no option block), then with "验收报告" (review report) when the result is back; its recommendation goes only in the "处理建议" (recommendation) section. In "验收报告":
1. **Precheck.** After writing the work order, the orchestrator sends a checker subagent to check the facts in it one by one: file paths, ids in the data, the release form and license of external resources, and whether each criterion can be verified. The orchestrator corrects what does not hold and puts trade-offs that need you under "需要决定" (decisions needed) in the review points. This step needs nothing from you.
2. **Review.** The orchestrator replies with "工单审阅" (work order review), listing only the review points and the order file path. The order can be issued only after you choose A; if the order changes after that, it is reviewed again.
3. **Execution.** The orchestrator dispatches an executor subagent in the background and replies with "工单执行" (order running). The executor checks the commit and assumptions, plans, implements, checks itself, and writes the receipt. "工单执行" needs no choice from you, so it has no option block; to stop and change the order midway, reply "停止执行" (stop).
4. **Waiting for your action.** When the order is fine and the executor only needs you to do something by hand (for example, one action in the program being debugged), it writes no receipt and hands back midway; the orchestrator replies with "等待操作" (waiting for your action) and lists the steps. Reply "操作完成" (done) with what you actually did, and the executor continues. This can repeat; the order status does not change.
5. **Blocked.** When the executor hits a specification problem, or needs a decision from you, it explains in the receipt and stops. The orchestrator replies with "受阻处理" (blocked handling); once you have handled it and the order does not need to change, the same executor continues without a new review. When only a few criteria cannot be met as written and the rest is unaffected, this is not blocked: the executor finishes the rest and lists those criteria as pending in the receipt, for you to decide at acceptance.
6. **Review of the work.** The orchestrator sends the reviewer subagent to check each criterion; the only verdicts are pass, fail, and unverified. While the reviewer works in the background, the orchestrator first replies with "工单验收" (order under review, no option block), then with "验收报告" (review report) when the result is back; its recommendation goes only in the "处理建议" (recommendation) section. In "验收报告":
- Everything passes: you may verify by hand following the "人工验收" (manual verification) steps, then choose to commit, or commit and push.
- Something fails: the orchestrator first judges why; an order that was too large is split, otherwise a fix order follows.
- Only unverified criteria remain: you decide to accept as is and commit, or to follow up; accepted unverified criteria are recorded as risks.
5. **Commit.** After acceptance, the orchestrator calls commit-message, and the business changes and records of the round become one commit. Changes outside the receipt are listed for you to decide.
- Only unverified criteria remain: you decide to accept as is and commit, or to follow up; accepted unverified criteria are recorded as risks. Criteria the receipt lists as pending are handled here too; "处理建议" (recommendation) states the facts and the options for each.
7. **Commit.** After acceptance, the orchestrator calls commit-message, and the business changes and records of the round become one commit. Changes outside the receipt are listed for you to decide.

Work orders run strictly one after another. The orchestrator sizes each order by four limits (one executor run can finish it, one review can check it, it runs afterwards, risky parts are separate), one slice per order by default, and states the reason in the review points.

Expand Down Expand Up @@ -173,7 +199,7 @@ B. 需要修改, 请提需求.
```
````

The conclusion line alone tells you what is asked of you; the details follow for when you need them. The parentheses at the end of the progress line show where the work order stands (起草中 drafting, 执行中 running, 受阻 blocked, 验收中 under review, 待你决定 awaiting your decision), which tells consecutive replies apart.
The conclusion line alone tells you what is asked of you; the details follow for when you need them. The parentheses at the end of the progress line show where the work order stands (起草中 drafting, 执行中 running, 待你操作 awaiting your action, 受阻 blocked, 验收中 under review, 待你决定 awaiting your decision), which tells consecutive replies apart.

## Record files

Expand Down
Loading
Loading