northstar

Northstar

Northstar 让代码仓库中的知识保持最新、计划清晰易读，这样任何 Agent 都能接手工作，无需从对话中重新还原意图。

代码仓库保存知识和代码。编排器（目前是 Paseo Queue 插件，之后是 Nucleus）保存流程和规划：计划（泳道、相关文档及其顺序）、负责人（包括简报）、小问题、任务、状态、审查、收尾和结果。两者都不要写入代码仓库。

代码仓库结构

界面	内容
AGENTS.md	导览：项目是什么、文档索引、护栏、验证命令
docs/README.md	当前事实，集中在一个页面，并按主题提供链接
docs/knowledge/	当前事实，每项事实只有一个归属文件：愿景、架构、契约、领域
docs/knowledge/retired.toml	已不再存在的概念，以及替代它们的内容
docs/knowledge/questions.md	尚未解决的问题，以及每个答案现在存放的位置
docs/knowledge/contracts/release.md	本项目的发布流程，逐步说明。每个项目都要有一份

这里没有 docs/plan.md、docs/triage/、任务卡、路线图、生成文件、交接文件、生命周期记录、交付日志或 PAPERCUTS.md。Git 历史和编排器的结果记录就是历史。

熟悉项目

阅读 AGENTS.md，然后阅读 docs/README.md，接着只阅读任务涉及的知识文件。要了解接下来要做什么，请阅读项目的 Queue 计划（plan.get）及其中列出的泳道文档。基于某个概念制定计划之前，请先检查 retired.toml。向操作人员提问之前，请先检查 questions.md 和对应的知识文件。重复询问已有答案的问题，代价高于查阅答案。

工作如何推进

1. 规划。 项目要推进的每项成果都对应一个 Queue 泳道，并有一份工作文档；项目计划会对泳道排序。尚未规划的想法和延期事项属于待处理事项。请参阅计划。
2. 编写简报。 每项任务都从 Queue 待处理事项中的一份简报开始，内容包括：成果、背景链接、限制条件、验收标准以及停止时机。请参阅简报。
3. 派发。 获得操作人员批准后，批准待处理事项并将其转为任务。Queue 会运行执行器、审查、合并和收尾流程，并保留结果。
4. 审查。 独立审查者根据简报检查确切的提交头。请参阅审查。
5. 保持知识最新。 工作改变了事实时，同一个 PR 会更新对应的知识文件。请参阅知识。

重要规则

• 每项事实只有一个归属文件。 链接到归属文件；不要重复陈述。副本将来会造成矛盾。
• 交接前落实裁定。 操作人员在对话中给出的答案，必须在对话结束或交接前写入对应的知识文件，或用于关闭 questions.md 中的问题。
• 退役记录要明确列出退役内容。 退役某个概念时，要在 retired.toml 中添加条目，列出涵盖的术语、路径和配置键；同一次变更还要移除或修正仍在使用的引用。
• 不镜像状态。 绝不要在代码仓库中写入“已完成”“已合并”或“正在审查”。状态由 Queue 管理。
• 为下一位读者而写。 只保留以后会用到的信息。内容要简短、直白，并说明理由，让人能理解决策。
• 如实说明破坏性变更。 变更破坏调用方或契约时，要明确说明并一并更新。不要用垫片掩盖决策。
• 每项任务运行有针对性的检查，在里程碑运行完整 QA（Tom，2026-09-30）。任务只运行能够验证变更的检查。整个测试套件由规划者在发布节点或完成重要工作后于 main 上运行。每项任务都运行完整 QA 会拖慢机器。
• 不要因机器负载而暂停工作。 只在高负载下失败的测试就是缺陷：记录并修复，而不是等机器空闲（Tom，2026-09-28）。

Shell 命令

这里的 Agent shell 通常是 macOS 上的 zsh。以下错误总是反复出现：

• 字面模式要用单引号。双引号中的反引号和 $(...) 会作为命令运行：rg 'use `foo`' docs，而不是 rg "use `foo`" docs。
• 将路径列表保存在数组中。zsh 不会拆分字符串变量，因此以空格分隔的列表会作为一个参数传入： files=(a.md b.md); for f in "${files[@]}"; do …; done。
• 不要使用 zsh 特殊变量名，例如 status、path 或 home。赋值给 status 会失败，而将 path 用作循环变量会导致命令查找出错。请使用 exit_code 和 rel_path 这样的名称。
• 冒号前要用花括号括住变量：git show "${rev}:tools/x.md"。zsh 会将 $rev:t… 读作修饰符，而 "$rev:tools/x.md" 会变成 HEADools/x.md。
• macOS 使用 BSD 版 sed 和 grep：没有 \b，sed -i 需要 ''，GNU 地址形式也会失败。请使用 rg、awk 或简短脚本提取文本。
• 绝不要按模式终止进程：不要使用 pkill -f、killall 或 pgrep … | xargs kill。其他任务的工作树共用这台机器，因此 pkill -f effigy 会终止机器上所有 Effigy 运行实例。只终止你启动的进程，使用 $! 获取的 PID 或你创建的进程组。
• 通过仓库的 Effigy 选择器运行验证，而不要直接运行 cargo、bun 或 vitest。可以使用范围较窄的选择器。Effigy 会在整台主机范围内调度高负载运行，而直接运行工具会绕过这一机制，让每个工作树都更容易发生资源争用。
• 记录后台任务的退出码，例如： cmd > run.log 2>&1; echo "exit=$?" >> run.log。进程已消失时，它可能已成功结束，因此不要把“已消失”当作失败。

小问题与线索

值得稍后修复、反复出现的小摩擦属于小问题，应记录到 Queue，而不是仓库中。Queue 调用从插件根目录（~/Dev/projects/paseo-northstar-queue）运行，并通过 stdin 传入负载。不要使用共享负载文件：另一个线程可能在两次调用之间覆盖它。

node bin/queue-cli.mjs papercut.add - <<'JSON'
{"repository": {"origin": "owner/name", "path": "/abs/checkout"},
 "title": "...", "happened": "...", "impact": "..."}
JSON

小问题需要包含 repository、title、happened 和 impact，还可以选择填写 area 和 fix。（papercut.list 将 repository 作为来源字符串，即 "owner/name"。）记录后继续执行任务。规划器会使用 papercut.promote-task 将小问题提升为任务（参见简介），使用 papercut.set-lanes 将其关联到一个泳道，或将其关闭为已完成或已弃用。

比摩擦问题更重大、尚未规划的观察、想法或问题属于线索：使用 lead.add（参见计划）。绝不要将任何一方写入文件。

需要询问操作员的情况

• 计划没有明确下一步该做什么；
• 某项选择会造成破坏、不可逆、涉及安全，或改变产品方向；
• 验证失败导致计划发生变化。

其他情况都应直接行动。对于已经确定的事项，再次询问授权只会带来成本。

如果一轮结束时需要操作员裁定，除了在聊天中询问，也要将其记录为 Queue 决策，以便显示在看板上，并将答复返回给你：

node bin/queue-cli.mjs decision.add - <<'JSON'
{"question": "...", "askedBy": "<your agent ID>", "options": ["A", "B"],
 "recommendation": "A, because ...", "context": "...",
 "project": {"origin": "owner/name", "path": "/abs/checkout"}}
JSON

关联相关任务、线索或小问题（tasks、leads、papercuts：ID 数组）。如果问题已不再适用，使用 decision.withdraw 撤回（参数为 id、version、reason、withdrawnBy）。如果问题发生变化，使用 decision.supersede 替代，而不是再新增一条。若操作员在聊天中给出裁定，请使用 decision.answer 记录，逐字引用操作员的答复，并在 note 中注明其姓名。无论哪种情况，裁定仍应写入其所属的知识文件，或关闭其 questions.md 条目：决策是当前待处理的问题，而不是记录本身。

角色

• 规划者（一个 Chatterbox 线程）：负责项目的 Queue 计划、泳道文档、负责人、知识维护、简报和调度审批请求。它直接将自己做的小型仓库更改（问题、写入知识文件的裁定、链接修复）提交到 main：运行仓库的文档检查，检查退出代码，然后推送。调度前，不要为小型知识编辑开 PR。较大或风险较高的更改则使用分支和自行合并的 PR，例如重构知识、迁移切换，或涉及代码、QA 配置或脚本的任何更改。对于这些更改，“通过”意味着退出代码为 0，且已实际检查。规划者还会在发布节点和完成主要工作后，通过 Queue 在 main 上运行仓库的完整 QA，而不是在本地运行：使用 project.qa.run，参数为 {"repository": "owner/name", "baseBranch": "main"}，然后使用 project.qa.get 获取结果。它会为发现的问题撰写修复简报。操作员不会审查规划者的更改；任何需要独立审查的事项都应通过 Queue 以简报形式处理。
• **工作者：**在 Queue 分配的工作树中完成一份简报，运行有针对性的检查（所改代码的测试、所改部分的编译，以及文档更改时的文档检查），仅运行一次，开一个 PR，通过 Queue 汇报，然后结束工作。不运行完整套件，也不重复检查。
• **审查者：**独立检查确切的最新提交：阅读差异，运行相同的有针对性检查，测试实际行为，并汇报发现。不运行套件。

协调工作（恢复、审查路由、合并、收尾）由 Queue 负责，而非线程。规划者使用 handover 将工作交接给新的继任者；不会创建交接文件。

接管或迁移仓库

使用 adopt 和 template/ 中的起始模板。采用旧版 Northstar 结构的仓库应通过一次明确的迁移切换完成迁移，并移除其 Queue 清单。

可选模块

UI 设计交付和语言质量包是独立模块。只有在仓库选择启用后，才加载其中一个。

• **UI：**嵌套的 northstar-ui 技能会依据已批准的设计简报构建和审查 UI 工作。其流程为 build 和 review。
• **语言包：**如需进行明确的 Rust 或 TypeScript/Svelte 质量审计，请遵循已安装软件包流程。该流程会运行技能的 language:route 任务。切勿从常规编码工作启动审计。
• 工作树：paseo:worktree 为 Paseo 工作树准备并关联同级检出；项目通过 paseo.json 的 setup 和 teardown 调用它。