@nathan33/nao-skill 0.1.0

package/.agents/templates/tasks-state.md.example

@@ -0,0 +1,34 @@
+# 任务状态（PM 维护，运行时事实）
+
+> 每次派发 / 回执 / 验收 / 抢占后更新本文件；PM 会话重开（`ensure --force`）后**先读本文件重建状态**再继续调度。
+> 归档后的历史见 `docs/prds/` 与 `docs/adr/`；本文件只记**运行时**任务状态，保持精简。
+
+## 待派发队列
+
+| 任务编号 | 目标会话 | 角色 | 概要 | 排队原因 |
+| :--- | :--- | :--- | :--- | :--- |
+| T3 | rd-be | 后端 | 实现 X 接口 | 目标忙碌 |
+
+## 进行中
+
+| 任务编号 | 目标会话 | 角色 | 概要 | 派发时间 | 对应 AC |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| T2 | rd-fe | 前端 | 登录页 + 校验 | 2026-09-21 14:00 | AC1/AC2 |
+
+## 已回执待验收
+
+| 任务编号 | 回执摘要（≤150字） | 详情路径 | 待办 |
+| :--- | :--- | :--- | :--- |
+| T1 | 创建 todo 链路完成 | docs/reports/T1.md | 核 AC 五覆盖 |
+
+## 挂起（被抢占 / 降级）
+
+| 任务编号 | 挂起原因 | 恢复方式 |
+| :--- | :--- | :--- |
+| — | — | — |
+
+## 已验收 / 已归档
+
+| 任务编号 | 结论 | 归档路径 |
+| :--- | :--- | :--- |
+| — | — | `docs/prds/` |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nathan Lee
+
+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/README.md

@@ -0,0 +1,189 @@
+# nao-skills
+
+多角色 AI 开发舰队的**角色卡 / 技能 / 协作协议 / 工具链**包，基于 [pi](https://pi.dev)（Agent Skills 标准 + pi-intercom 多会话）。Made by [Nathan Lee](https://github.com/nathan)。
+
+核心命题：**用最少的 Token，把多个专业 Agent 会话组织成一个可靠交付的团队**——常驻精简、按需加载、机器强制、终态回执。
+
+## 整体架构
+
+```text
+┌──────────────────────────────────────────────────────────────────┐
+│ 项目级上下文   AGENTS.md（PM 维护 · pi 自动注入所有会话 · 最高优先级）│
+├──────────────────────────────────────────────────────────────────┤
+│ 协作层    pi-intercom：派发 / ask-reply / 终态回执闸门             │
+│          PM=状态权威：忙闲闸门 → 排队/抢占 → 验收 → 归档            │
+├──────────────────────────────────────────────────────────────────┤
+│ 单一事实来源   roles.yaml（aliases→id→card）· 卡片 frontmatter     │
+├──────────────────────────────────────────────────────────────────┤
+│ 常驻层（每轮计费，刻意精简）                                      │
+│          角色卡：身份/职责/2-3 条最硬红线/按需指针                  │
+│          common/：output-format + intercom-protocol              │
+├──────────────────────────────────────────────────────────────────┤
+│ 按需层（渐进式披露，零常驻 token）                                │
+│          skills/   DDD 细节 · codegraph · commit                 │
+│          checklists/（独立于 skills/，避 pi 注册）· frontend-design/│
+│          templates/   frontend-ui · AGENTS.md · tasks-state 骨架 │
+├──────────────────────────────────────────────────────────────────┤
+│ 工具层    nao-fleet.sh（ensure/check/status）+ ui-tokens-check   │
+├──────────────────────────────────────────────────────────────────┤
+│ 外部能力  CodeGraph 索引（代码定位，替代 grep 全文扫描）           │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### 分层职责
+
+| 层 | 内容 | Token 特性 |
+| --- | --- | --- |
+| **项目级** | 项目根 `AGENTS.md`（PM 维护 §七）：项目属性/约束，pi 自动注入所有会话 | 常驻（限 <120 行） |
+| **协作层** | pi-intercom：`--name` 注册身份，send/ask/reply 线程化；终态回执闸门（`[编号] done \| <role>` 必回） | 消息短、详情落盘 |
+| **单一事实来源** | `roles.yaml` 管别名→角色；卡片 frontmatter `version` 管版本；两处互相校验（`check`） | 无重复维护 |
+| **常驻层** | 5 张角色卡（60–112 行）+ 2 份 common 规范——每轮每会话计费，**刻意保持最小** | 最贵，最小化 |
+| **按需层** | skills + checklists + templates：只有 description 常驻，完整指令按需读取（Agent Skills 标准渐进式披露） | 常态零成本 |
+| **工具层** | fleet 拉起/体检/状态；ui-tokens-check 硬编码色值扫描（可接 CI） | 一次性执行 |
+| **外部能力** | CodeGraph：`context` 一次返回相关符号+代码块（实测约 1/17 于 grep+全文） | 查找精准化 |
+
+## 核心设计：Token 优先
+
+1. **常驻最小化**：红线/清单/速查表全部按需化到 `checklists/`（独立目录，避开 pi skill 扫描），卡片只留最硬红线 + 指针。
+2. **按需加载**：Agent Skills 渐进式披露——DDD 细节、官方 frontend-design、checklists 均按需读，不占常驻。
+3. **缓存友好**：system prompt 稳定 = 前缀缓存命中（cacheRead 约 1/10 价）；改卡**批量一次到位**，易变内容放消息体不进卡片；`cacheWarming: "idle"` + `/session` 观察。
+4. **查找精准**：CodeGraph `context`/`node`/`callers`/`impact` 替代 grep+cat 全文；不可用时降级 grep + `sed` 行段读取（禁 cat 全文）。
+5. **上下文生命周期**：任务闭环 → `ensure --force` 重开会话（优于自动压缩）；PM 靠 `docs/` 落盘延续，不靠历史消息堆叠。
+
+## 上下文三层分层
+
+| 层 | 载体 | 维护者 | 内容 |
+| --- | --- | --- | --- |
+| **项目级（最高）** | 项目根 `AGENTS.md` | PM（§七） | 项目属性/约束/机制衔接；pi 自动注入所有会话，**优先于角色默认习惯** |
+| **团队级** | `roles.yaml` + `common/` | nao-skills 仓库 | 角色清单、协作协议、终态回执、缓存纪律 |
+| **角色级** | `prompts/` + `skills/` + `checklists/` | nao-skills 仓库 | 角色身份/边界、按需技能、交付清单 |
+
+各层各写各的、不互相复制；项目已有非空 AGENTS.md 时**合并追加**（保留原文 + `## nao 舰队接入` 区块，可回退），不覆盖。
+
+## 协作闭环（PM 为 leader）
+
+```
+用户提需求 → PM grill-me 澄清 → 9 模块 PRD + RICE
+  → 开工确认卡（用户确认）→ AGENTS.md 项目上下文就绪（新建/合并）
+  → fleet ensure 拉起缺线角色 → 架构评审闸门（arch 签字 / ADR）
+  → send 派发（忙闲闸门：idle 才派 / 忙则排队 / 紧急抢占）
+  → worker 终态回执 `[编号] done`（未回执 PM 主动追讨）
+  → 验收闭环（AC 五覆盖）→ tasks-state.md 更新 → docs/prds 当日归档
+```
+
+## 任务调度：状态机 + 忙闲闸门 + 可恢复
+
+PM 是任务状态权威，以状态机驱动执行：
+
+| 状态 | 转移条件 |
+| --- | --- |
+| `queued`（待派发） | 目标忙碌（`thinking`/`tool:*`），记入 `docs/tasks-state.md` |
+| `dispatched`（进行中） | `list` 显示目标 `idle` 才派完整任务 |
+| `done`（已回执） | worker 回 `[编号] done`；PM 校验后进入验收 |
+| `verified`（已验收） | AC 五覆盖核对通过，归档 `docs/prds` |
+
+- **忙闲闸门**：`list` 的 live status（`idle`/`thinking`/`tool:*`）为判定依据；忙时**不 send 任务内容**（非交互拒收 / 交互 steer 打断），直接排队；紧急才抢占（交互可 steer 注入 + 注明挂起，非交互只能排队）。
+- **状态外部化**：`docs/tasks-state.md` 五栏（待派发/进行中/待验收/挂起/已归档）随每次派发·回执·验收更新；PM 会话重开先读文件重建状态，不依赖历史消息。
+
+- **终态回执硬闸门**：所有角色（含 arch 评审）必须以回执模板结束任务；`send` 失败降级 `ask` → 再失败才降级交付。
+- **卡片版本同步**：改卡 bump `version` 并广播 `card <role> vN`（不贴全文）；worker 接任务前核对版本，stale 则重读。
+- **降级**：PM 可达必须回执；intercom 不可用才允许"本会话直接产出 + 用户转交"。
+
+## 代码定位（CodeGraph）
+
+`@.agents/skills/codegraph.md`（按需）——`query`/`context`/`node`/`callers`/`callees`/`impact`/`affected` 速查 + token 纪律 + 降级 grep 规则。索引项目级维护：`status` → `init`/`sync`；`nao-fleet.sh` 的 `check`/`ensure` 自动探测索引健康并提醒。
+
+## UI/UX 落地（三层，不绑定组件库）
+
+| 层 | 载体 | 职责 |
+| --- | --- | --- |
+| 设计质量层 | 官方 `frontend-design` skill（按需） | 视觉方向、反 AI 味、typography |
+| 约束层 | Design Tokens（`--<prefix>-*`）+ UX Playbook + `ui-tokens-check.sh` | 令牌收敛、四态/反馈一致、机器扫描 |
+| 验收层 | checklist rd-fe / qa | 交付前核对 + QA 视觉验收 |
+
+模板：`templates/frontend-ui/`（tokens.css + ux-playbook 骨架，任意项目复制裁剪）。
+
+## 角色卡（常驻 system prompt）
+
+| Prompt | Role | 核心职责 |
+| --- | --- | --- |
+| `product-manager.md` | 产品经理（调度者） | 需求全生命周期、9 模块 PRD、RICE、多会话调度、终态回执闸门、**§七 AGENTS.md 项目上下文治理**、§十一 docs/prds 归档 |
+| `architecture-designer.md` | 系统架构师（评审/咨询） | 技术选型四步法、评审签字 + ADR、终态回执 PM、降级规则 |
+| `frontend-developer.md` | 前端研发 | 前端 DDD 五层、UI/UX 三层落地（引用 frontend-design） |
+| `backend-developer.md` | 后端研发 | Go DDD 四层、依赖倒置、事务/事件/错误约定 |
+| `test-engineer.md` | 测试工程师 | 测试金字塔、AC=用例、缺陷闭环、视觉验收 |
+
+所有角色卡头部均声明：**项目根 `AGENTS.md` 已由 pi 注入、最高优先级、优先于本卡默认习惯**（含各自执行点：arch 评审输入、RD 命令纪律、QA 环境运行）。
+
+## 按需技能
+
+| Skill | 用途 |
+| --- | --- |
+| `frontend-ddd-details.md` | 前端 DDD 骨架/场景速决/命名/误区 + UI/UX 落地 |
+| `backend-ddd-details.md` | 后端 DDD 骨架/事务/事件/命名/误区 |
+| `arch-patterns.md` | 架构模式、ADR 模板 |
+| `pm-rice.md` / `pm-grill.md` | RICE 优先级 / 需求澄清 |
+| `test-design.md` | 用例设计、缺陷管理、分层对齐 |
+| `codegraph.md` | 代码定位（替代 grep 全文） |
+| `commit.md` | git commit 规范（仅提交前读） |
+| `frontend-design/` | 官方视觉方向 skill（设计类任务先读） |
+| `checklists/*.md` | 各角色完整红线 + 交付检查清单（交付前读） |
+
+## 工具链
+
+```bash
+.agents/scripts/nao-fleet.sh check                    # 体检：roles.yaml/卡片/交叉引用/白名单/布局/CodeGraph
+.agents/scripts/nao-fleet.sh status                   # 角色在线状态（权威名单见 intercom list）
+.agents/scripts/nao-fleet.sh ensure arch rd-fe        # 拉起缺失角色
+.agents/scripts/nao-fleet.sh ensure rd-be@/path/repo  # 指定后端 repo（含 CodeGraph 索引提醒）
+.agents/scripts/ui-tokens-check.sh <repo>             # 扫 UI 硬编码色值（绕过 Design Tokens）
+```
+
+## 安装（npm 发布）
+
+发布为 **`@nathan33/nao-skill`**，提供 `nao-skill install` CLI 一键接入项目：
+
+```bash
+npm install -g @nathan33/nao-skill          # 全局安装 CLI
+# 或在任意项目里直接：npx @nathan33/nao-skill install
+
+nao-skill install                            # 安装到当前目录
+nao-skill install /path/to/proj --force      # 指定目录；--force 覆盖同名文件
+```
+
+- **安装内容**：`.agents/` 全套（角色卡 / 技能 / 交付清单 / 协议 / roles.yaml / 工具链 / 模板）+ 生成 `AGENTS.md`（已存在则提示按 §七 合并，不覆盖）。
+- **合并策略**：目标已有同名文件默认保留项目既有（避免覆盖自定义）；`--force` 备份后覆盖。
+- **发布**：`npm publish --access public`（scope 包需 `--access public`）。
+
+## 目录结构
+
+```text
+nao-skills/
+└── .agents/
+    ├── common/                    # 常驻规范（全部角色引用）
+    │   ├── output-format.md       # 输出/回执模板、反模式
+    │   └── intercom-protocol.md   # 多会话协议、终态回执、版本同步、缓存纪律
+    ├── roles.yaml                 # 角色清单（aliases→id→card，单一事实来源）
+    ├── prompts/                   # 角色卡（frontmatter: role/version/updated）
+    │   ├── product-manager.md     └── architecture-designer.md
+    │   ├── frontend-developer.md  └── backend-developer.md
+    │   └── test-engineer.md
+    ├── checklists/                 # 红线+交付清单（交付前读；独立于 skills/ 避免被 pi 注册为同名 skill）
+    │   ├── pm.md / architecture-designer.md / rd-be.md / rd-fe.md / qa.md
+    ├── skills/                    # 按需技能（渐进式披露）
+    │   ├── frontend-design/       # 官方设计方向 skill（按需）
+    │   ├── frontend-ddd-details.md / backend-ddd-details.md
+    │   ├── arch-patterns.md / pm-rice.md / pm-grill.md
+    │   ├── test-design.md / codegraph.md / commit.md
+    ├── templates/                  # 项目接入骨架（供复制裁剪）
+    │   ├── AGENTS.md.example        # 项目级上下文（PM 维护，合并规则见 PM 卡 §七）
+    │   ├── tasks-state.md.example   # 任务状态机落盘（待派发/进行中/待验收/挂起/已归档）
+    │   └── frontend-ui/             # tokens.css + ux-playbook 骨架
+    └── scripts/
+        ├── nao-fleet.sh           # 会话拉起 / 在线状态 / 静态体检
+        └── ui-tokens-check.sh     # UI 硬编码色值扫描
+```
+
+## License
+
+MIT © 2026 Nathan Lee

package/bin/nao-skill.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * nao-skill — nao 多角色 AI 开发舰队安装器
+ *
+ * 用法
+ *   nao-skill install [dir] [--force]  把 .agents/ 能力安装到目标项目（默认当前目录）
+ *   nao-skill --version               版本
+ *   nao-skill --help                  帮助
+ *
+ * 行为
+ *   - 目标项目无 .agents/ → 完整复制
+ *   - 已有 .agents/       → 合并：同名条目保留项目既有（--force 则备份后覆盖）
+ *   - 无 AGENTS.md        → 由模板生成（项目级上下文，PM 维护）
+ *   - 已有 AGENTS.md      → 提示按 PM 卡 §七 合并规则手动追加，不自动覆盖
+ *
+ * 使用（安装后）
+ *   bash .agents/scripts/nao-fleet.sh check / ensure arch rd-fe ...
+ *   角色卡经 fleet 拉起时 --append-system-prompt 注入；checklists 按需读取
+ */
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  rmSync,
+  statSync,
+} from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const SRC = fileURLToPath(new URL('../.agents', import.meta.url));
+const TEMPLATE_AGENTS = fileURLToPath(new URL('../.agents/templates/AGENTS.md.example', import.meta.url));
+
+const log = (...a) => console.log('[nao-skill]', ...a);
+const warn = (...a) => console.error('[nao-skill]', ...a);
+
+function copyDir(src, dst, force) {
+  const entries = readdirSync(src, { withFileTypes: true });
+  let copied = 0, skipped = 0, overwritten = 0;
+  for (const e of entries) {
+    const s = join(src, e.name);
+    const d = join(dst, e.name);
+    if (existsSync(d)) {
+      if (force) {
+        rmSync(d, { recursive: true, force: true });
+        cpSync(s, d, { recursive: true });
+        overwritten++;
+      } else {
+        skipped++;
+      }
+    } else {
+      cpSync(s, d, { recursive: true });
+      copied++;
+    }
+  }
+  return { copied, skipped, overwritten };
+}
+
+function install(target, force) {
+  if (!existsSync(SRC)) {
+    warn(`包内 .agents 缺失：${SRC}（发布物损坏？）`);
+    process.exit(1);
+  }
+  const dst = join(target, '.agents');
+  if (!existsSync(dst)) {
+    mkdirSync(dst, { recursive: true });
+    cpSync(SRC, dst, { recursive: true });
+    log(`已完整安装 .agents/ → ${dst}`);
+  } else {
+    const r = copyDir(SRC, dst, force);
+    log(`合并完成：复制 ${r.copied}，跳过 ${r.skipped}（已存在），覆盖 ${r.overwritten}`);
+    if (r.skipped > 0 && !force) {
+      warn('同名文件保留项目既有版本（避免覆盖自定义）；需要覆盖加 --force。');
+    }
+  }
+
+  const agentsMd = join(target, 'AGENTS.md');
+  if (!existsSync(agentsMd)) {
+    let tpl = readFileSync(TEMPLATE_AGENTS, 'utf8');
+    tpl = tpl.replaceAll('<项目名>', basename(resolve(target)));
+    writeFileSync(agentsMd, tpl);
+    log('已生成 AGENTS.md（项目级上下文，PM 维护；保持精简 <120 行）。');
+  } else {
+    warn('AGENTS.md 已存在：按 PM 卡 §七 合并规则手动追加「nao 舰队接入」区块，勿覆盖原文。');
+  }
+
+  log('');
+  log('✔ 安装完成。下一步：');
+  log('  bash .agents/scripts/nao-fleet.sh check                       # 体检');
+  log('  bash .agents/scripts/nao-fleet.sh status                      # 在线状态');
+  log('  bash .agents/scripts/nao-fleet.sh ensure arch rd-fe rd-be qa  # 拉起舰队');
+  log('  角色卡：.agents/prompts/ · 技能：.agents/skills/ · 交付清单：.agents/checklists/');
+}
+
+function help() {
+  console.log(`nao-skill v${PKG.version} — nao 多角色 AI 开发舰队安装器
+
+用法:
+  nao-skill install [dir] [--force]   安装/合并 .agents/ 到目标项目（默认当前目录）
+  nao-skill --version                 显示版本
+  nao-skill --help                    显示本帮助
+
+安装内容: 角色卡(prompts/) · 技能(skills/) · 交付清单(checklists/) · 协作协议(common/) ·
+          roles.yaml · 工具链(scripts/) · 模板(templates/) · AGENTS.md 生成/合并提示
+
+说明: 目标项目已有同名文件时默认保留（--force 覆盖）；AGENTS.md 已存在时按合并规则手动追加。
+`);
+}
+
+function statIsDir(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
+  console.log(PKG.version);
+} else if (cmd === '--help' || cmd === '-h' || cmd === 'help' || !cmd) {
+  help();
+} else if (cmd === 'install' || cmd === 'i') {
+  let target = process.cwd();
+  let force = false;
+  const rest = args.slice(1);
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === '--force' || rest[i] === '-f') force = true;
+    else if (rest[i] === '--target') target = resolve(rest[++i]);
+    else if (!rest[i].startsWith('-')) target = resolve(rest[i]);
+    else { warn(`未知参数: ${rest[i]}`); process.exit(2); }
+  }
+  if (!existsSync(target) || !statIsDir(target)) {
+    warn(`目标目录无效: ${target}`);
+    process.exit(2);
+  }
+  install(target, force);
+} else {
+  warn(`未知命令: ${cmd}（可用: install）`);
+  process.exit(2);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@nathan33/nao-skill",
+  "version": "0.1.0",
+  "description": "nao 多角色 AI 开发舰队：角色卡 / 技能 / 协作协议 / 工具链，一键接入项目（pi / Claude / 任意 Agent）",
+  "type": "module",
+  "bin": {
+    "nao-skill": "bin/nao-skill.js"
+  },
+  "files": [
+    "bin/",
+    ".agents/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "skills",
+    "multi-agent",
+    "pi",
+    "claude",
+    "design-system",
+    "codegraph"
+  ],
+  "author": "Nathan Lee",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "bash .agents/scripts/nao-fleet.sh check",
+    "prepack": "bash .agents/scripts/nao-fleet.sh check"
+  }
+}