ys-team 0.2.0

package/docs/specs/completed/20260407-161500-npm-skill-installer/control.md

@@ -0,0 +1,117 @@
+---
+Spec-Type: control
+Initiative: 20260407-161500-npm-skill-installer
+Status: completed
+Owner-Session: ys-team
+Write-Scope: []
+Depends-On: []
+Parallel-With: []
+Blocked-By: ""
+Verification: "Manual review of npm CLI behavior, README/docs consistency, and package dry-run output."
+Integration-Gate: |
+  1. npm 包不再只是分发静态内容，而是能完成最小核心安装动作。
+  2. `ys-team` CLI 能把 skills 安装到用户本地 skills 目录。
+  3. 安装行为具备明确边界，不误导用户以为已实现完整 init 安装器。
+  4. README、项目文档与 CLI 输出保持一致。
+---
+
+# npm 技能安装器落地
+
+## Background
+
+当前 npm 包已经能发布 `ys-team` 仓库内容，但 CLI 只会输出说明，无法完成实际安装动作。
+
+这导致“npm 安装 ys-team”仍停留在文档建议层，而不是一个可执行入口。
+
+## Goals
+
+- 给 npm 包补上最小但真实可用的技能安装能力
+- 保持边界清晰，不把 npm 包误写成完整 init/rebuild 自动化器
+- 让 README 和项目文档同步表达新的 npm 入口
+
+## Non-goals
+
+- 本次不自动改写目标项目的 `AGENTS.md` / `CLAUDE.md`
+- 本次不自动执行 `ys-team-init`
+- 本次不实现跨平台复杂安装向导
+
+## Deliverables
+
+- 一个可执行的 `ys-team install-skills` CLI
+- 与之对应的 README 和项目文档更新
+- 一份收口证据
+
+## Acceptance Criteria
+
+- `npx ys-team install-skills` 默认能安装到本地 skills 目录
+- CLI 支持显式目标目录和安全覆盖控制
+- README 能说明 npm 当前已支持与未支持的能力
+
+## Collaboration Summary
+
+- Participants:
+  - method-architect
+  - product-evolution-owner
+  - delivery-guard
+- Participant Titles:
+  - 方法论架构师
+  - 产品演进负责人
+  - 交付守门人
+- Discussion Rounds:
+  - 1
+- Escalations:
+  - None
+- Reporter:
+  - method-architect
+- Reporter Title:
+  - 方法论架构师
+- Estimated Cost:
+  - 1
+- Submit Recommendation:
+  - Yes
+
+## Discussion Digest
+
+- 方法论架构师：
+  - npm 面应先补最小核心动作，不要跳到完整安装器。
+- 产品演进负责人：
+  - 用户最先需要的是“安装 skills 成功”，不是一次性自动改完所有项目文件。
+- 交付守门人：
+  - CLI、README、package dry-run 和证据必须同次交付闭环。
+
+## Delivery Plan
+
+- `work-01`：实现 `install-skills` CLI 与文件复制逻辑
+- `work-02`：同步 README / docs / package 验证说明
+
+## Verification
+
+- 运行 `node scripts/ys-team.mjs install-skills --dest /tmp/ys-team-install-check --force`
+- 运行 `node scripts/ys-team.mjs install-skills --dest /tmp/ys-team-install-check-dry --dry-run`
+- 运行 `npm pack --dry-run`
+
+## Acceptance Evidence
+
+### 文件清单
+
+- `docs/specs/active/20260407-161500-npm-skill-installer/control.md`
+
+### 验收要求
+
+- CLI 行为与文档表述一致，且安装行为可以被人工复核
+
+## Documentation Updates
+
+- `README.md`
+- `docs/project/overview.md`
+- `docs/project/structure.md`
+- `docs/project/module-index.md`
+
+## Risks
+
+- 如果默认安装目录判断错误，可能把 skills 安装到用户不期望的位置
+- 如果覆盖策略过于激进，可能破坏用户本地已有 skills
+
+## Rollback Plan
+
+- 回退到只保留说明型 CLI，同时保留 package 分发能力

package/docs/specs/completed/20260407-161500-npm-skill-installer/evidence/20260407-npm-installer-closeout.md

@@ -0,0 +1,38 @@
+# Closeout Evidence
+
+## Scope
+
+本次交付覆盖：
+
+- `ys-team install-skills` CLI
+- README / 项目文档中的 npm 安装说明
+- npm dry-run 分发验证
+
+## Verification
+
+### `node scripts/ys-team.mjs --help`
+
+- 结果：PASS
+- 说明：CLI 已展示 `install-skills` 命令、默认目录和 npm 边界
+
+### `node scripts/ys-team.mjs install-skills --dest /tmp/ys-team-install-check --force`
+
+- 结果：PASS
+- 说明：9 个 bundled skills 已复制到目标目录
+
+### `node scripts/ys-team.mjs install-skills --dest /tmp/ys-team-install-check-dry --dry-run`
+
+- 结果：PASS
+- 说明：dry-run 仅输出计划动作，不落文件
+
+### `npm pack --dry-run`
+
+- 结果：PASS
+- 说明：tarball 已包含 CLI、文档、spec 和 bundled skills
+
+## Acceptance Conclusion
+
+PASS
+
+- npm 包已具备真实可用的最小安装动作
+- 文档与 CLI 行为一致，且边界仍保持清晰

package/docs/specs/completed/20260407-161500-npm-skill-installer/work-01-cli-install-skills.md

@@ -0,0 +1,58 @@
+---
+Spec-Type: work
+Initiative: 20260407-161500-npm-skill-installer
+Status: completed
+Owner-Session: ys-team
+Write-Scope:
+  - scripts/
+  - package.json
+Depends-On: []
+Parallel-With: []
+Blocked-By: ""
+Verification: "`node scripts/ys-team.mjs install-skills --dest /tmp/ys-team-install-check --force` and `--dry-run`."
+Integration-Gate: ""
+---
+
+# Work 01 CLI skills 安装能力
+
+## Background
+
+现有 npm CLI 只有说明输出，没有实际安装行为。
+
+## Goals
+
+- 补齐 `install-skills` 命令
+- 默认安装到用户本地 skills 目录
+- 保持覆盖策略安全且可控
+
+## Deliverables
+
+- `ys-team install-skills`
+- 默认目录解析与复制逻辑
+- `--dest` / `--force` / `--dry-run`
+
+## Acceptance Criteria
+
+- CLI 能把包内 `skills/` 安装到目标目录
+- 未使用 `--force` 时，不覆盖已有 skill
+- `--dry-run` 只展示计划动作，不落文件
+
+## Verification
+
+- 运行安装和 dry-run 命令，人工检查目标目录结果
+
+## Acceptance Evidence
+
+- `docs/specs/active/20260407-161500-npm-skill-installer/work-01-cli-install-skills.md`
+
+## Documentation Updates
+
+- `README.md`
+
+## Risks
+
+- 默认路径推断和覆盖策略不当会降低可用性
+
+## Rollback Plan
+
+- 回退到仅支持显式 `--dest` 的安装模式

package/docs/specs/completed/20260407-161500-npm-skill-installer/work-02-doc-and-package-surface.md

@@ -0,0 +1,61 @@
+---
+Spec-Type: work
+Initiative: 20260407-161500-npm-skill-installer
+Status: completed
+Owner-Session: ys-team
+Write-Scope:
+  - README.md
+  - docs/project/
+  - package.json
+Depends-On: []
+Parallel-With: []
+Blocked-By: ""
+Verification: "Manual review plus `npm pack --dry-run`."
+Integration-Gate: ""
+---
+
+# Work 02 npm 文档与分发表面同步
+
+## Background
+
+CLI 能力变化后，README 和项目文档必须同步，不然用户会继续把 npm 面理解成只读说明。
+
+## Goals
+
+- 同步 npm 已支持与未支持的边界
+- 让 README 给出可执行示例
+- 保持 package dry-run 可验证
+
+## Deliverables
+
+- 更新后的 README 和项目文档
+- package 分发验证
+
+## Acceptance Criteria
+
+- README 已包含 npm 安装示例
+- 项目文档反映 npm CLI 是最小安装器，而非完整 init 安装器
+
+## Verification
+
+- 人工检查 README/docs 和 CLI 输出一致
+- `npm pack --dry-run`
+
+## Acceptance Evidence
+
+- `docs/specs/active/20260407-161500-npm-skill-installer/work-02-doc-and-package-surface.md`
+
+## Documentation Updates
+
+- `README.md`
+- `docs/project/overview.md`
+- `docs/project/structure.md`
+- `docs/project/module-index.md`
+
+## Risks
+
+- 文案若写得过满，会抬高用户对自动化程度的预期
+
+## Rollback Plan
+
+- 回退到只保留 CLI 帮助输出和 package 分发说明

package/examples/baseline/.ys_team/README.md

@@ -0,0 +1,5 @@
+# baseline local ys-team
+
+这是默认工作流骨架的示例 `.ys_team/`。
+
+`ys-team-init` 应以这里的结构为来源，再结合具体项目现实生成项目自己的 `.ys_team/`。

package/examples/baseline/.ys_team/VERSION

@@ -0,0 +1 @@
+0.2.0

package/examples/baseline/.ys_team/evolution/requests.md

@@ -0,0 +1,12 @@
+# 进化申请
+
+工作流在运行过程中主动感知到的能力缺口，记录在此。
+由 spec-talk 或 spec-work 自动写入，团队评估后决定是否引入。
+
+## 待处理
+
+（无）
+
+## 已处理
+
+（无）

package/examples/baseline/.ys_team/methods.md

@@ -0,0 +1,54 @@
+# Methods
+
+## Principle
+
+默认工作流采用“弱引导、强结果”。
+
+含义：
+
+- 先理解当前是在讨论需求、起草 spec、执行工作，还是做验收判断。
+- 不把所有对话强行套进固定流程图。
+- 每轮讨论都要收敛到明确结论、现状和下一步。
+
+## Result Card
+
+每轮重要讨论至少应收敛到：
+
+- `Current Mode`
+- `Decision`
+- `Current State`
+- `Why`
+- `Needed Changes`
+- `Next Step`
+
+## Role Brief
+
+每轮讨论默认给出角色简报，说明当前判断、风险和下一步。
+
+## Decision Meanings
+
+- `PASS`
+- `BLOCKED`
+- `REJECT`
+
+## External Escalation
+
+如果 internal team 认为需要 external role：
+
+1. 先停止继续扩展讨论
+2. 明确提出 external support request
+3. 等用户同意后再继续
+
+## Execution Intent
+
+当问题已经收敛到可执行程度时，默认应继续进入 spec / work / acceptance 链，而不是停在抽象讨论。
+
+## Discussion Lens
+
+项目可按场景装载思维透镜，例如：
+
+- 第一性原理
+- 苏格拉底提问
+- 奥卡姆剃刀
+
+它们用于帮助收敛，不构成固定流程。

package/examples/baseline/.ys_team/policy.md

@@ -0,0 +1,81 @@
+# Policy
+
+## Execution Rules
+
+- 非 trivial 改动先以 `docs/specs/` 为准。
+- 文档必须反映项目当前真实状态。
+- spec、实现和验收证据应保持同一次交付闭环。
+- 默认保持最小公开心智，不为了“看起来完整”而把内部能力暴露成用户菜单。
+
+## Documentation Authority
+
+项目应声明：
+
+- 哪些文档承载当前现实
+- 哪些文档承载接口或结构说明
+- 哪些文档承载 roadmap / spec
+- 哪些文档是代码变化后必须同步更新的权威来源
+
+## Reality Index
+
+现实索引（`docs/project/module-index.md`）是 AI 团队各角色对项目模块现实达成共识的基础设施。
+
+- **承载内容**：模块划分、业务职责摘要（2–3 句）、模块间依赖关系
+- **维护时机**：模块新增、模块职责重大变化、模块间依赖关系变化时更新
+- **维护方式**：运行 `ys-team-doc-build`（`ys-team-rebuild` 时自动调用）
+- **使用时机**：control 阶段快速判断影响范围；work 阶段 Write-Scope 语义对齐；evidence 阶段生成验收检查点
+- **读取优先**：在讨论改动前，先读索引，再决定是否需要深入代码
+
+## Documentation Sync Rules
+
+项目应定义：
+
+- 实现变化时哪些文档必须同步更新
+- 对外行为变化时哪些说明必须更新
+
+## Spec Rules
+
+- control / work 写入 `docs/specs/<phase>/<initiative-id>/`
+- evidence 放在对应 initiative 的 `evidence/`
+- verification 必须可执行或可复核
+- work 的 write-scope 必须明确到文件或目录
+
+## Submit Gate
+
+项目应定义哪些情况需要更重的交付复核，例如：
+
+- 数据迁移
+- 对外接口行为变化
+- 多模块联动
+- 外部回调或异步链路上线
+
+## 并行策略
+
+```yaml
+spec_parallel: false      # 多个不相关 spec 可同时执行
+role_parallel: false       # 同一 spec 内多角色可并行工作
+```
+
+### Spec 级并行（spec_parallel）
+
+启用后，多个不相关的 spec 可同时走 spec-work → submit 链。
+
+- 类似多个 feature branch 同时开发
+- 冲突检测：如果两个 spec 的 write-scope 涉及同一模块，降级为串行，并在 status.md 中标注冲突
+- 每条并行线在 status.md 中独立追踪
+
+### 角色级并行（role_parallel）
+
+启用后，同一 spec 内多个角色可并行工作。
+
+- 如 project-architect 做设计时 delivery-guard 同步准备验收标准
+- 讨论收敛后汇总各角色结果
+- 角色间有依赖时仍需串行（如 architect 的设计完成后 domain-integrator 才能评估集成面）
+
+### 默认关闭
+
+并行能力默认关闭。项目在确认以下条件后可在 rebuild 时开启：
+
+- 团队对 ys-team 工作流已熟悉
+- status 数据追踪正常运行
+- 项目模块边界清晰（现实索引完整）

package/examples/baseline/.ys_team/roles/external/db-migration-auditor.md

@@ -0,0 +1,5 @@
+# db-migration-auditor
+Title: 数据迁移审计顾问
+subagent_policy: preferred
+
+负责 schema 变更、数据回填、回滚风险和迁移可验证性审查。

package/examples/baseline/.ys_team/roles/external/frontend-accessibility-reviewer.md

@@ -0,0 +1,5 @@
+# frontend-accessibility-reviewer
+Title: 前端可用性顾问
+subagent_policy: preferred
+
+负责前端交互、可访问性和用户入口一致性审查。

package/examples/baseline/.ys_team/roles/external/observability-reviewer.md

@@ -0,0 +1,5 @@
+# observability-reviewer
+Title: 可观测性与性能顾问
+subagent_policy: preferred
+
+负责日志、指标、追踪、容量与性能相关风险审查。

package/examples/baseline/.ys_team/roles/external/security-reviewer.md

@@ -0,0 +1,5 @@
+# security-reviewer
+Title: 安全审查顾问
+subagent_policy: preferred
+
+负责安全边界、输入输出风险、回调与外部交互的安全性审查。

package/examples/baseline/.ys_team/roles/internal/delivery-guard.md

@@ -0,0 +1,5 @@
+# delivery-guard
+Title: 交付与验收守门人
+subagent_policy: local_only
+
+负责验证口径、证据要求、风险控制、回滚和交付闭环。

package/examples/baseline/.ys_team/roles/internal/doc-spec-steward.md

@@ -0,0 +1,5 @@
+# doc-spec-steward
+Title: 文档与规格负责人
+subagent_policy: local_only
+
+负责共享现实索引、spec 结构、模板和项目说明的一致性。

package/examples/baseline/.ys_team/roles/internal/domain-integrator.md

@@ -0,0 +1,5 @@
+# domain-integrator
+Title: 领域与集成负责人
+subagent_policy: local_only
+
+负责领域契约、上下游集成面、外部系统适配和关键边界映射。

package/examples/baseline/.ys_team/roles/internal/project-architect.md

@@ -0,0 +1,5 @@
+# project-architect
+Title: 项目架构负责人
+subagent_policy: local_only
+
+负责系统边界、主链路、模块职责和整体收敛判断。

package/examples/baseline/.ys_team/status.md

@@ -0,0 +1,23 @@
+# 团队状态
+
+updated: —
+
+## 活跃 Spec
+
+| Spec | 阶段 | 负责角色 | 状态 |
+|------|------|---------|------|
+| — | — | — | — |
+
+## 最新判断
+
+| 时间 | Spec | 角色 | 决定 | 原因 |
+|------|------|------|------|------|
+| — | — | — | — | — |
+
+## 阻塞项
+
+（无）
+
+## 待办
+
+（无）

package/examples/baseline/.ys_team/team.md

@@ -0,0 +1,34 @@
+# Team
+
+## Default Team
+
+- `project-architect`
+  - tools: []
+- `domain-integrator`
+  - tools: []
+- `doc-spec-steward`
+  - tools: []
+- `delivery-guard`
+  - tools: []
+
+## Selection Rules
+
+- 涉及系统边界、模块职责和主链路设计时，必须包含 `project-architect`。
+- 涉及外部系统、契约、集成面或领域适配时，必须包含 `domain-integrator`。
+- 涉及项目文档、spec、模板或对外说明时，必须包含 `doc-spec-steward`。
+- 涉及验收、风险、回滚和证据时，必须包含 `delivery-guard`。
+
+## Tools Binding
+
+角色的 `tools` 字段列出该角色已绑定的内化工具（来自 `.ys_team/toolbox/`）。
+
+- 工具在角色对应的工作流环节自动建议使用
+- 工具绑定由 init/rebuild 时的内化流程写入
+- 手动修改时需确保 toolbox 中存在对应的内化文件
+
+## Available External Candidates
+
+- `security-reviewer`
+- `db-migration-auditor`
+- `observability-reviewer`
+- `frontend-accessibility-reviewer`

package/examples/baseline/.ys_team/templates/control.md

@@ -0,0 +1,31 @@
+---
+Spec-Type: control
+Initiative: <YYYYMMDD-HHMMSS-name>
+Status: draft
+Owner-Session: ys-team
+Write-Scope: []
+Depends-On: []
+Verification: "<directly executable command or explicit manual review steps>"
+---
+
+# <Initiative Title>
+
+## Background
+
+## Goals
+
+## Deliverables
+
+## Acceptance Criteria
+
+## Collaboration Summary
+
+## Verification
+
+## Acceptance Evidence
+
+## Documentation Updates
+
+## Risks
+
+## Rollback Plan

package/examples/baseline/.ys_team/templates/roadmap-version.md

@@ -0,0 +1,20 @@
+---
+Roadmap-Type: version
+Initiative: <YYYYMMDD-HHMMSS-name>
+Status: draft
+Owner-Session: ys-team
+---
+
+# <Roadmap Title>
+
+## Background
+
+## Goals
+
+## Scope
+
+## Milestones
+
+## Risks
+
+## Exit Criteria

package/examples/baseline/.ys_team/templates/work.md

@@ -0,0 +1,30 @@
+---
+Spec-Type: work
+Initiative: <YYYYMMDD-HHMMSS-name>
+Status: draft
+Owner-Session: ys-team
+Write-Scope:
+  - <file-or-dir>
+Depends-On: []
+Verification: "<directly executable command or explicit manual review steps>"
+---
+
+# <Work Title>
+
+## Background
+
+## Goals
+
+## Deliverables
+
+## Acceptance Criteria
+
+## Verification
+
+## Acceptance Evidence
+
+## Documentation Updates
+
+## Risks
+
+## Rollback Plan

package/examples/baseline/.ys_team/toolbox/_candidates.md

@@ -0,0 +1,7 @@
+# 内化候选
+
+用户在工作流中显式使用了未内化的 skill 时，自动记录在此。
+下次 rebuild 时作为内化评估的输入。
+
+| Skill 名称 | 使用场景 | 记录时间 |
+|------------|---------|---------|

package/examples/baseline/.ys_team/toolbox/_sources.md

@@ -0,0 +1,7 @@
+# 工具源索引
+
+本文件记录团队已内化的外部工具来源，由 init/rebuild 自动维护。
+
+| 能力名称 | 原 Skill | 版本 | 来源 URL | 内化日期 |
+|----------|----------|------|----------|----------|
+| — | — | — | — | — |