Skip to content

feat(waypoint)!: project-navigator 改为以切片为单位, 骨架先行并核对接线与模块化 #29

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
auYeCoding merged 1 commit into from
Nov 12, 2026
Merged

feat(waypoint)!: project-navigator 改为以切片为单位, 骨架先行并核对接线与模块化 #29

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
3 changes: 0 additions & 3 deletions .github/workflows/validate.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,3 @@ jobs:

- name: Run tests
run: npm test

- name: Check generated documents
run: npm run gen:docs -- --check
2 changes: 1 addition & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,5 +13,5 @@
- 自然语言文本遵守 [标点规则](plugins/waypoint/shared/punctuation.md): 英文 (ASCII) 标点, 每个标点后加一个空格.
- 提交消息用 `waypoint:commit-message` 技能生成, 不附加任何署名.
- 提交前运行 `npm run format`, `npm run validate` 与 `npm test`.
- `project-navigator` 的 `references/replies.md`, `references/files.md`, `references/writing.md` 与 `guide/executor.md` 是生成文件. 修改 `spec/templates.json`, `scripts/navigator-docs/` 或 `shared/punctuation.md` 后运行 `npm run gen:docs`, 不直接改生成文件.
- `project-navigator` 中每条知识只有一个来源: 切片文件的小节在 `spec/slice.json`, 下一动作在 `runtime/lib/guidance.mjs`, 委派提示词在 `runtime/lib/briefs.mjs`, 工程规范在 `standards/engineering.md`. 规则文件引用它们, 不重复写.
- 运行脚本只用 Node.js 内置模块; 每个声明都写 JSDoc, 函数体内不写注释.
6 changes: 3 additions & 3 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ plugins/<plugin>/ One directory per plugin, installed and versio
docs/<skill>.md, <skill>.en.md Detailed guide for each skill, in Simplified Chinese and English
README.md, README.en.md Plugin overview and skill index, in Simplified Chinese and English
CHANGELOG.md Plugin changelog
scripts/ Repository tooling, including the project-navigator document generator
scripts/ Repository tooling
tests/ Automated tests, run with npm test
.github/ Issue forms, pull request template, CI workflows, and README assets
```
Expand Down Expand Up @@ -55,7 +55,7 @@ Prerequisites: Git, Node.js 22 or later, and [Claude Code](https://code.claude.c
```

2. Make your change and [test it locally](#testing-locally).
3. Format, validate, and test. If you changed the `project-navigator` spec or the sources in `scripts/navigator-docs/`, run `npm run gen:docs` first:
3. Format, validate, and test:

```bash
npm run format
Expand All @@ -67,7 +67,7 @@ Prerequisites: Git, Node.js 22 or later, and [Claude Code](https://code.claude.c
5. Push the branch to your fork and open a pull request against `main`. Fill in the pull request template.
6. Keep the pull request focused on one change. If `main` moves ahead, rebase your branch onto `upstream/main` instead of merging it in.

CI runs the same format, validation, and test checks on every pull request, and checks that the generated `project-navigator` documents are in sync. A pull request can be merged only after these checks pass, and only a maintainer can merge it.
CI runs the same format, validation, and test checks on every pull request. A pull request can be merged only after these checks pass, and only a maintainer can merge it.

## Testing locally

Expand Down
30 changes: 15 additions & 15 deletions MAINTAINING.en.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,19 @@ This guide is for maintainers. It lists what else needs updating when you change

## Change checklist

| What you changed | What else to update |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Any Chinese document | Its English counterpart (`*.en.md`), and the other way around |
| A skill's behavior (`SKILL.md` or `references/`) | The skill's Chinese and English guides, the skill summary in the plugin and root READMEs (if its purpose changed), and `Unreleased` in `CHANGELOG.md` |
| A skill's `description` | Test automatic triggering again by hand (see [Pre-release manual tests](#pre-release-manual-tests)) |
| `shared/punctuation.md` | Every skill is affected, so test them all; also run `npm run gen:docs`, because the generated documents of `project-navigator` embed the punctuation rules |
| The spec, runtime, or document sources of `project-navigator` | See the [project-navigator maintainer guide](plugins/waypoint/docs/project-navigator-maintaining.en.md#change-process) |
| A new skill | See [Adding a skill](#adding-a-skill) |
| A new plugin | See [Adding a plugin](#adding-a-plugin) |
| Anything users will notice in a plugin | Release it: bump `version` in `plugin.json`, or users never receive the change |
| The CI job name (`validate.yml`) | The required check name in the GitHub branch rules, or no pull request can be merged |
| What the banner shows, such as the skill list | Regenerate the PNG and upload the social preview again in the GitHub settings |
| The repository, user, marketplace, or plugin name | See [Hard-coded names and links](#hard-coded-names-and-links) |
| What you changed | What else to update |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Any Chinese document | Its English counterpart (`*.en.md`), and the other way around |
| A skill's behavior (`SKILL.md` or `references/`) | The skill's Chinese and English guides, the skill summary in the plugin and root READMEs (if its purpose changed), and `Unreleased` in `CHANGELOG.md` |
| A skill's `description` | Test automatic triggering again by hand (see [Pre-release manual tests](#pre-release-manual-tests)) |
| `shared/punctuation.md` | Every skill is affected, so test them all |
| The spec, runtime, or rule files of `project-navigator` | See the [project-navigator maintainer guide](plugins/waypoint/docs/project-navigator-maintaining.en.md#change-process) |
| A new skill | See [Adding a skill](#adding-a-skill) |
| A new plugin | See [Adding a plugin](#adding-a-plugin) |
| Anything users will notice in a plugin | Release it: bump `version` in `plugin.json`, or users never receive the change |
| The CI job name (`validate.yml`) | The required check name in the GitHub branch rules, or no pull request can be merged |
| What the banner shows, such as the skill list | Regenerate the PNG and upload the social preview again in the GitHub settings |
| The repository, user, marketplace, or plugin name | See [Hard-coded names and links](#hard-coded-names-and-links) |

## Documentation

Expand Down Expand Up @@ -146,7 +146,7 @@ These settings live on GitHub, not in the repository files. Check them whenever
- **After upgrading `@anthropic-ai/claude-code`**, the new validator may report new warnings. CI runs with `--strict`, so warnings fail the build. Fix the plugin files as reported instead of dropping `--strict`.
- **GitHub Actions** are pinned to full commit SHAs with the version in a comment, and dependabot upgrades them.
- **Node.js:** CI uses version 24. `engines` in `package.json` requires 22 or later, because the Claude Code npm package does.
- **Before committing**, run `npm run format`, `npm run validate`, and `npm test`. After changing the spec or document sources of `project-navigator`, run `npm run gen:docs` first. CI runs the same checks, and confirms with `npm run gen:docs -- --check` that the generated documents are in sync.
- **Before committing**, run `npm run format`, `npm run validate`, and `npm test`. CI runs the same checks.

## Hard-coded names and links

Expand All @@ -158,7 +158,7 @@ When the repository moves or something is renamed, replace every occurrence belo
| User `auYeCoding` | `owner` in `marketplace.json`, `author` in `plugin.json`, `.github/CODEOWNERS`, `LICENSE` |
| Marketplace `radish-plugins` | `name` in `marketplace.json`, the install, update, and uninstall commands in the READMEs, local testing in `CONTRIBUTING.md`, the banner source |
| Plugin `waypoint` | `marketplace.json`, `plugin.json`, the plugin table, commands, and version badge URL in the READMEs, examples in `CONTRIBUTING.md`, examples in the issue forms, the banner source, the subagent and skill names in the `project-navigator` guard (`runtime/lib/guard.mjs`) |
| State directory `.navigator` | `runtime/lib/paths.mjs` of `project-navigator`, the allow rules (`runtime/lib/settings.mjs`), its references and guides |
| State directory `.navigator` | `runtime/lib/paths.mjs` of `project-navigator` (including the archive directory name `.navigator-1.x`), the allow rules (`runtime/lib/settings.mjs`), its references and guides |
| Command `project-navigator` | The plugin's `bin/project-navigator` and `bin/project-navigator.cmd`, `COMMAND_NAME` in `runtime/lib/paths.mjs`, the allow rules, `allowed-tools` in `SKILL.md`, and its references |
| Code of Conduct contact email | `CODE_OF_CONDUCT.md` |

Expand Down
30 changes: 15 additions & 15 deletions MAINTAINING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,19 @@

## 改动同步速查表

| 你改了什么 | 还需要同步的地方 |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| 任何中文文档 | 对应的英文文档 (`*.en.md`), 反之亦然 |
| 技能的行为 (`SKILL.md` 或 `references/`) | 该技能的中英文文档, 插件 README 与根 README 中的简介 (若用途变化), `CHANGELOG.md` 的 `Unreleased` |
| 技能的 `description` | 重新手动测试自动触发 (见 [发版前手动测试](#发版前手动测试)) |
| `shared/punctuation.md` | 所有技能都会受影响, 都要测试; 还要运行 `npm run gen:docs`, 因为 `project-navigator` 的生成文档内嵌了标点规则 |
| `project-navigator` 的规格, 运行脚本或文档源文件 | 见 [project-navigator 维护文档](plugins/waypoint/docs/project-navigator-maintaining.md#修改流程) |
| 新增技能 | 见 [新增技能](#新增技能) |
| 新增插件 | 见 [新增插件](#新增插件) |
| 插件的对外表现 | 发版: 提升 `plugin.json` 中的 `version`, 否则用户收不到更新 |
| CI 任务名 (`validate.yml`) | GitHub 分支规则中的必需检查名, 否则所有 PR 都无法合并 |
| 横幅图展示的内容 (如技能列表) | 重新生成 PNG, 并在 GitHub 设置中重新上传社交预览图 |
| 仓库名, 用户名, 市场名或插件名 | 见 [写死的名称与链接](#写死的名称与链接) |
| 你改了什么 | 还需要同步的地方 |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| 任何中文文档 | 对应的英文文档 (`*.en.md`), 反之亦然 |
| 技能的行为 (`SKILL.md` 或 `references/`) | 该技能的中英文文档, 插件 README 与根 README 中的简介 (若用途变化), `CHANGELOG.md` 的 `Unreleased` |
| 技能的 `description` | 重新手动测试自动触发 (见 [发版前手动测试](#发版前手动测试)) |
| `shared/punctuation.md` | 所有技能都会受影响, 都要测试 |
| `project-navigator` 的规格, 运行脚本或规则文件 | 见 [project-navigator 维护文档](plugins/waypoint/docs/project-navigator-maintaining.md#修改流程) |
| 新增技能 | 见 [新增技能](#新增技能) |
| 新增插件 | 见 [新增插件](#新增插件) |
| 插件的对外表现 | 发版: 提升 `plugin.json` 中的 `version`, 否则用户收不到更新 |
| CI 任务名 (`validate.yml`) | GitHub 分支规则中的必需检查名, 否则所有 PR 都无法合并 |
| 横幅图展示的内容 (如技能列表) | 重新生成 PNG, 并在 GitHub 设置中重新上传社交预览图 |
| 仓库名, 用户名, 市场名或插件名 | 见 [写死的名称与链接](#写死的名称与链接) |

## 文档

Expand Down Expand Up @@ -146,7 +146,7 @@
- **升级 `@anthropic-ai/claude-code` 后**, 新版校验器可能新增警告, 而 CI 以 `--strict` 运行, 警告也会导致失败. 这时要按提示修改插件文件, 而不是去掉 `--strict`.
- **GitHub Actions** 固定到完整的提交 SHA, 并在注释中写明版本, 由 dependabot 统一升级.
- **Node.js:** CI 使用 24; `package.json` 的 `engines` 要求 22 及以上, 因为 Claude Code 的 npm 包要求 22 及以上.
- **提交前**运行 `npm run format`, `npm run validate` 与 `npm test`; 改了 `project-navigator` 的规格或文档源文件时, 先运行 `npm run gen:docs`. CI 执行同样的检查, 并以 `npm run gen:docs -- --check` 确认生成文档已同步.
- **提交前**运行 `npm run format`, `npm run validate` 与 `npm test`. CI 执行同样的检查.

## 写死的名称与链接

Expand All @@ -158,7 +158,7 @@
| 用户名 `auYeCoding` | `marketplace.json` 的 `owner`, `plugin.json` 的 `author`, `.github/CODEOWNERS`, `LICENSE` |
| 市场名 `radish-plugins` | `marketplace.json` 的 `name`, README 中的安装, 更新与卸载命令, `CONTRIBUTING.md` 的本地测试, 横幅源文件 |
| 插件名 `waypoint` | `marketplace.json`, `plugin.json`, README 的插件表, 命令与版本徽章地址, `CONTRIBUTING.md` 的示例, issue 模板的示例, 横幅源文件, `project-navigator` 守卫中的子代理与技能名 (`runtime/lib/guard.mjs`) |
| 状态目录名 `.navigator` | `project-navigator` 的 `runtime/lib/paths.mjs`, 放行规则 (`runtime/lib/settings.mjs`), 参考文件与文档 |
| 状态目录名 `.navigator` | `project-navigator` 的 `runtime/lib/paths.mjs` (含归档目录名 `.navigator-1.x`), 放行规则 (`runtime/lib/settings.mjs`), 参考文件与文档 |
| 命令名 `project-navigator` | 插件的 `bin/project-navigator` 与 `bin/project-navigator.cmd`, `runtime/lib/paths.mjs` 的 `COMMAND_NAME`, 放行规则, `SKILL.md` 的 `allowed-tools` 与参考文件 |
| 行为准则联系邮箱 | `CODE_OF_CONDUCT.md` |

Expand Down
Loading
Loading