ys-team 0.2.0

package/examples/baseline/AGENTS.md

@@ -0,0 +1,51 @@
+# AGENTS.md
+
+## 最高优先级工作流
+
+本仓库使用 `ys-team` 排他工作流。
+
+**任何请求必须先经过 `ys-team` 路由。**
+
+**如果当前回复末尾没有出现 `ys-team` 可见标志，视为不在 ys-team 工作流中，必须立即切回路由。**
+
+Trivial 改动定义（可直接执行，无需 spec）：
+- 单文件修改
+- 无跨模块影响
+- 无回滚风险
+- 用户明确说明是 trivial（如"修拼写错误"、"改注释"）
+
+**如果不确定是否 trivial，必须触发 ys-team-spec-talk。**
+
+## Skill 排他规则
+
+**禁止自动触发 `.ys_team/toolbox/` 以外的任何 skill。**
+
+已内化的工具清单见 `.ys_team/toolbox/_sources.md`。
+仅这些工具的能力（以内化后的版本为准）在工作流中可用。
+
+用户如需临时使用未内化的 skill，必须显式指定（如 `/skill-name`）。
+此时 ys-team 记录该使用行为，作为下次 rebuild 的内化候选。
+
+## 例外
+
+用户在 CLAUDE.md 中显式声明的全局 skill 不受此规则限制。
+
+## 可见标志规则
+
+只要正在执行 `ys-team` 工作流，回复末尾必须出现以下其一：
+
+- 路由判断：`` `ys-team` · [判断结果] → [下一步] ``
+- discussion / spec-talk：`**[主持人]** ys-team · spec-talk`
+- spec-work：`**[执行中]** ys-team · spec-work`
+- submit：`**[验收]** ys-team · submit`
+- status：`**[状态]** ys-team · status`
+
+如果缺少这些标志，直接要求：
+
+`请先进入 ys-team 工作流，并给出当前阶段标志。`
+
+## 现实索引
+
+项目现实索引位于 `docs/project/module-index.md`。
+
+在讨论影响范围、编写 spec 或评估改动风险时，先读取该索引，而不是直接探索代码库。

package/examples/baseline/CLAUDE.md

@@ -0,0 +1,32 @@
+# CLAUDE.md
+
+本项目启用 `ys-team` 工作流后，默认进入排他模式。
+
+## 首先做什么
+
+- 先判断当前请求是否已进入 `ys-team` 路由
+- 如果不是 trivial 改动，先进入 discussion / spec 链路
+
+## 工作流可见标志
+
+正在执行 `ys-team` 时，回复末尾必须出现以下其一：
+
+- 路由判断：`` `ys-team` · [判断结果] → [下一步] ``
+- discussion / spec-talk：`**[主持人]** ys-team · spec-talk`
+- spec-work：`**[执行中]** ys-team · spec-work`
+- submit：`**[验收]** ys-team · submit`
+- status：`**[状态]** ys-team · status`
+
+如果没有这些标志，直接要求：
+
+`请先进入 ys-team 工作流，并给出当前阶段标志。`
+
+## 排他规则
+
+- 禁止自动触发 `.ys_team/toolbox/` 以外的任何 skill
+- 用户在仓库自己的 `CLAUDE.md` 中显式声明的全局 skill 例外
+
+## 现实索引
+
+- 先读取 `docs/project/module-index.md`
+- 再判断影响范围和是否需要 spec

package/examples/baseline/README.md

@@ -0,0 +1,54 @@
+# baseline
+
+`baseline` 是 `ys-team` 当前默认工作流的公开承载。
+
+它不是某个项目的完整复制品，而是从已验证项目工作流中提纯出来的默认骨架。
+
+## 作用
+
+- 作为 `ys-team-init` 的默认工作流来源
+- 作为使用者理解“初始化后项目会长成什么样”的样例
+- 作为后续新增 preset 前的默认 baseline
+
+## 设计原则
+
+- 保留通用协作机制
+- 保留 spec-first 骨架
+- 保留角色、模板、证据和文档同步机制
+- 不保留具体项目的领域角色、目录结构和技术栈命令
+
+## 包含内容
+
+- `.ys_team/`
+- `docs/specs/`
+- `docs/roadmap/`
+- `docs/project/`
+
+## 默认能力目标
+
+基于 `baseline` 初始化后的项目，应直接具备这条默认链路：
+
+- discussion
+- spec
+- work
+- acceptance
+
+这些能力可以由多个静默内部 skills 支撑，但不要求用户主动点名调用。
+
+## 可见标志
+
+初始化后的项目在执行 `ys-team` 工作流时，回复末尾必须出现明显标志：
+
+- 路由判断：`` `ys-team` · [判断结果] → [下一步] ``
+- discussion / spec-talk：`**[主持人]** ys-team · spec-talk`
+- spec-work：`**[执行中]** ys-team · spec-work`
+- submit：`**[验收]** ys-team · submit`
+- status：`**[状态]** ys-team · status`
+
+如果没有这些标志，说明当前还没有真正进入 ys-team 工作流。
+
+## 不包含内容
+
+- 某个单一项目的领域角色
+- 某个语言栈的固定验证命令
+- 某个业务系统的目录映射

package/examples/baseline/docs/project/overview.md

@@ -0,0 +1,5 @@
+# baseline 项目概览示例
+
+这里用于展示一个项目在接入 `ys-team` 之后，应该如何维护自己的现实索引。
+
+真实项目应把这里替换成自己的现状说明。

package/examples/baseline/docs/roadmap/active/.gitkeep

@@ -0,0 +1 @@
+

package/examples/baseline/docs/roadmap/cancelled/.gitkeep

@@ -0,0 +1 @@
+

package/examples/baseline/docs/roadmap/completed/.gitkeep

@@ -0,0 +1 @@
+

package/examples/baseline/docs/roadmap/queued/.gitkeep

@@ -0,0 +1 @@
+

package/examples/baseline/docs/specs/active/.gitkeep

@@ -0,0 +1 @@
+

package/examples/baseline/docs/specs/cancelled/.gitkeep

@@ -0,0 +1 @@
+

package/examples/baseline/docs/specs/completed/.gitkeep

@@ -0,0 +1 @@
+

package/examples/baseline/docs/specs/queued/.gitkeep

@@ -0,0 +1 @@
+

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "ys-team",
+  "version": "0.2.0",
+  "description": "AI 团队治理方法论：以共享现实索引为对齐基础、以 Spec 为执行与验收统一依据的轻量治理框架",
+  "keywords": [
+    "claude-code",
+    "ai-team",
+    "governance",
+    "spec-first",
+    "skills"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dwp7399/ys-team"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "ys-team": "./scripts/ys-team.mjs"
+  },
+  "files": [
+    "skills/",
+    "examples/",
+    "registry/",
+    "scripts/",
+    "docs/",
+    "README.md",
+    "AGENTS.md",
+    "CLAUDE.md"
+  ]
+}

package/registry/frontend-react.md

@@ -0,0 +1,10 @@
+# 前端 (React) 项目工具推荐
+
+在通用推荐基础上，额外推荐以下工具。
+
+## 推荐列表
+
+| 工具 | 用途 | 绑定角色建议 | 来源 |
+|------|------|-------------|------|
+| frontend-design | 前端界面设计规范 | project-architect | frontend-design:frontend-design |
+| test-driven-development | TDD 开发流程 | project-architect | superpowers:test-driven-development |

package/registry/fullstack.md

@@ -0,0 +1,10 @@
+# 全栈项目工具推荐
+
+在通用推荐基础上，额外推荐以下工具。
+
+## 推荐列表
+
+| 工具 | 用途 | 绑定角色建议 | 来源 |
+|------|------|-------------|------|
+| frontend-design | 前端界面设计规范 | project-architect | frontend-design:frontend-design |
+| test-driven-development | TDD 开发流程 | project-architect | superpowers:test-driven-development |

package/registry/general.md

@@ -0,0 +1,16 @@
+# 通用工具推荐
+
+适用于所有项目类型的基础工具推荐。
+
+## 推荐列表
+
+| 工具 | 用途 | 绑定角色建议 | 来源 |
+|------|------|-------------|------|
+| verification-before-completion | 完成前验证检查 | delivery-guard | superpowers:verification-before-completion |
+| systematic-debugging | 系统化调试流程 | project-architect | superpowers:systematic-debugging |
+
+## 说明
+
+- 以上为默认推荐，init 时根据项目扫描结果自动匹配
+- 如果推荐的 skill 未安装，提示用户安装或跳过
+- 内化时选择性提取，不要求完整复制

package/registry/java-backend.md

@@ -0,0 +1,9 @@
+# Java 后端项目工具推荐
+
+在通用推荐基础上，额外推荐以下工具。
+
+## 推荐列表
+
+| 工具 | 用途 | 绑定角色建议 | 来源 |
+|------|------|-------------|------|
+| test-driven-development | TDD 开发流程 | project-architect | superpowers:test-driven-development |

package/registry/python-backend.md

@@ -0,0 +1,9 @@
+# Python 后端项目工具推荐
+
+在通用推荐基础上，额外推荐以下工具。
+
+## 推荐列表
+
+| 工具 | 用途 | 绑定角色建议 | 来源 |
+|------|------|-------------|------|
+| test-driven-development | TDD 开发流程 | project-architect | superpowers:test-driven-development |

package/scripts/hooks-template.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://docs.anthropic.com/claude-code/settings-schema.json",
+  "_comment": "ys-team hooks 配置模板。将此内容合并到项目的 .claude/settings.json 中。",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "command": "echo '[ys-team-hook] file_changed' >> .ys_team/status-events.log"
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "command": "echo '[ys-team-hook] session_end' >> .ys_team/status-events.log"
+      }
+    ]
+  }
+}

package/scripts/ys-team.mjs

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, "..");
+const bundledSkillsDir = path.join(packageRoot, "skills");
+const baselineAgentsPath = path.join(packageRoot, "examples", "baseline", "AGENTS.md");
+const baselineClaudePath = path.join(packageRoot, "examples", "baseline", "CLAUDE.md");
+
+function defaultSkillsDir() {
+  return path.join(os.homedir(), ".agents", "skills");
+}
+
+function helpText() {
+  return [
+    "ys-team npm surface",
+    "",
+    "This package currently distributes repository assets and can install bundled ys-team skills.",
+    "",
+    "Commands:",
+    "- ys-team --help",
+    "- ys-team install-skills [--dest <dir>] [--force] [--dry-run]",
+    "- ys-team init-project [--dir <project-dir>] [--force] [--dry-run]",
+    "",
+    "Default global install destination:",
+    `- ${defaultSkillsDir()}`,
+    "",
+    "Default project-local install destination:",
+    "- <project>/.agents/skills",
+    "",
+    "Included:",
+    "- skills/",
+    "- examples/baseline/",
+    "- registry/",
+    "- docs/",
+    "- scripts/",
+    "",
+    "Visible workflow markers:",
+    "- route: `ys-team` · [decision] -> [next step]",
+    "- spec-talk: [主持人] ys-team · spec-talk",
+    "- spec-work: [执行中] ys-team · spec-work",
+    "- submit: [验收] ys-team · submit",
+    "- status: [状态] ys-team · status",
+    "",
+    "Current npm boundaries:",
+    "- installs bundled ys-team skills into ~/.agents/skills for global use",
+    "- can initialize project-local .agents/skills plus baseline AGENTS.md / CLAUDE.md",
+    "- does not automatically execute ys-team-init",
+    "- is ready to publish, but actual npm registry publish still needs npm account credentials",
+    "",
+    "Recommended next step after install:",
+    "1. For global mode: run ys-team-init in the target repository.",
+    "2. For project mode: open the target repository and continue with ys-team-init there."
+  ].join("\n");
+}
+
+function parseArgs(argv) {
+  const args = {
+    command: null,
+    dest: defaultSkillsDir(),
+    dir: process.cwd(),
+    force: false,
+    dryRun: false,
+    help: false
+  };
+
+  const rest = argv.slice(2);
+  if (rest.length === 0) {
+    args.help = true;
+    return args;
+  }
+
+  for (let i = 0; i < rest.length; i += 1) {
+    const value = rest[i];
+    if (value === "--help" || value === "-h") {
+      args.help = true;
+      continue;
+    }
+    if (!args.command && !value.startsWith("--")) {
+      args.command = value;
+      continue;
+    }
+    if (value === "--dest") {
+      const next = rest[i + 1];
+      if (!next) {
+        throw new Error("Missing value for --dest");
+      }
+      args.dest = path.resolve(next);
+      i += 1;
+      continue;
+    }
+    if (value === "--dir") {
+      const next = rest[i + 1];
+      if (!next) {
+        throw new Error("Missing value for --dir");
+      }
+      args.dir = path.resolve(next);
+      i += 1;
+      continue;
+    }
+    if (value === "--force") {
+      args.force = true;
+      continue;
+    }
+    if (value === "--dry-run") {
+      args.dryRun = true;
+      continue;
+    }
+    throw new Error(`Unsupported argument: ${value}`);
+  }
+
+  return args;
+}
+
+function ensureBundledSkills() {
+  if (!fs.existsSync(bundledSkillsDir)) {
+    throw new Error(`Bundled skills directory not found: ${bundledSkillsDir}`);
+  }
+  if (!fs.existsSync(baselineAgentsPath) || !fs.existsSync(baselineClaudePath)) {
+    throw new Error("Baseline AGENTS.md / CLAUDE.md templates not found");
+  }
+}
+
+function listBundledSkills() {
+  ensureBundledSkills();
+  return fs.readdirSync(bundledSkillsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function copyDirectoryRecursive(sourceDir, targetDir) {
+  fs.mkdirSync(targetDir, { recursive: true });
+  for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+    if (entry.isDirectory()) {
+      copyDirectoryRecursive(sourcePath, targetPath);
+    } else {
+      fs.copyFileSync(sourcePath, targetPath);
+    }
+  }
+}
+
+function copyFileWithPolicy(sourcePath, targetPath, { force, dryRun }) {
+  const exists = fs.existsSync(targetPath);
+  if (exists && !force) {
+    return { action: "skipped", targetPath };
+  }
+
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.copyFileSync(sourcePath, targetPath);
+  }
+
+  return { action: exists ? "replaced" : "created", targetPath };
+}
+
+function installSkills({ dest, force, dryRun }) {
+  const skills = listBundledSkills();
+  const operations = [];
+  const skipped = [];
+
+  for (const skill of skills) {
+    const sourcePath = path.join(bundledSkillsDir, skill);
+    const targetPath = path.join(dest, skill);
+    const exists = fs.existsSync(targetPath);
+
+    if (exists && !force) {
+      skipped.push(skill);
+      continue;
+    }
+
+    operations.push({ skill, sourcePath, targetPath, replace: exists });
+  }
+
+  if (!dryRun) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const op of operations) {
+      if (op.replace) {
+        fs.rmSync(op.targetPath, { recursive: true, force: true });
+      }
+      copyDirectoryRecursive(op.sourcePath, op.targetPath);
+    }
+  }
+
+  const lines = [
+    dryRun ? "ys-team install-skills dry-run" : "ys-team install-skills",
+    "",
+    `destination: ${dest}`,
+    `bundled skills: ${skills.length}`,
+    `scheduled installs: ${operations.length}`,
+    `skipped existing: ${skipped.length}`
+  ];
+
+  if (operations.length > 0) {
+    lines.push("", "planned:");
+    for (const op of operations) {
+      lines.push(`- ${op.skill}${op.replace ? " (replace)" : ""}`);
+    }
+  }
+
+  if (skipped.length > 0) {
+    lines.push("", "skipped:");
+    for (const skill of skipped) {
+      lines.push(`- ${skill}`);
+    }
+    lines.push("", "Use --force to replace existing installed skills.");
+  }
+
+  if (!dryRun && operations.length > 0) {
+    lines.push("", "next:");
+    lines.push("- run ys-team-init in the target repository");
+    lines.push("- update AGENTS.md and CLAUDE.md so ys-team is the highest-priority workflow");
+  }
+
+  return lines.join("\n");
+}
+
+function initProject({ dir, force, dryRun }) {
+  const skillsDest = path.join(dir, ".agents", "skills");
+  const agentsDest = path.join(dir, "AGENTS.md");
+  const claudeDest = path.join(dir, "CLAUDE.md");
+
+  const installSummary = installSkills({
+    dest: skillsDest,
+    force,
+    dryRun
+  });
+
+  const agentsResult = copyFileWithPolicy(baselineAgentsPath, agentsDest, { force, dryRun });
+  const claudeResult = copyFileWithPolicy(baselineClaudePath, claudeDest, { force, dryRun });
+
+  return [
+    dryRun ? "ys-team init-project dry-run" : "ys-team init-project",
+    "",
+    `project: ${dir}`,
+    `local skills: ${skillsDest}`,
+    `AGENTS.md: ${agentsResult.action}`,
+    `CLAUDE.md: ${claudeResult.action}`,
+    "",
+    installSummary,
+    "",
+    "next:",
+    "- open the target repository",
+    "- run ys-team-init in that repository",
+    "- verify AGENTS.md and CLAUDE.md match your project-local needs"
+  ].join("\n");
+}
+
+function main() {
+  try {
+    const args = parseArgs(process.argv);
+
+    if (args.help || !args.command) {
+      console.log(helpText());
+      process.exit(0);
+    }
+
+    if (args.command === "install-skills") {
+      console.log(installSkills(args));
+      process.exit(0);
+    }
+
+    if (args.command === "init-project") {
+      console.log(initProject(args));
+      process.exit(0);
+    }
+
+    console.error(`Unsupported command: ${args.command}`);
+    console.error("Run `ys-team --help`.");
+    process.exit(1);
+  } catch (error) {
+    console.error(`ys-team error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/skills/ys-team/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: ys-team
+description: "Entry skill for the ys-team method. Use it to explain the method, keep decisions anchored in repository reality, and route users toward project init or local rebuild when needed."
+---
+
+# ys-team
+
+`ys-team` 是一种以共享现实索引为对齐基础、以多角色讨论为收敛机制、以 Spec 为执行与验收统一依据的 AI 团队治理方法。
+
+## The Zen of ys-team
+
+- 现实先于生成。
+- 规格先于执行。
+- 讨论归于收敛。
+- 证据胜于感觉。
+
+## Purpose
+
+Use `ys-team` as the public entry skill for this method.
+
+Its job is to keep the conversation anchored in:
+
+- repository reality
+- role-based convergence
+- spec-first execution
+- evidence-based acceptance
+
+## Public Model
+
+对外只保留很少的用户心智：
+
+1. 先把 ys-team skills 装好
+2. 在项目里执行一次 `ys-team-init`
+3. 项目形态明显变化后，再执行 `ys-team-rebuild`
+
+不要把内部实现细节包装成用户必须理解的流程图。
+
+默认工作流由 `examples/baseline/` 承载。
+
+## Core Invariants
+
+- 项目必须维护共享现实索引，并随真实变化同步更新。
+- 非 trivial 工作先形成 Spec，再按 Spec 执行和验收。
+- 讨论的目标是收敛，而不是无边界扩展。
+- 交付必须留下可复核证据。
+
+## Routing Guidance
+
+- 如果用户想先理解方法论，直接解释 `ys-team`，不要急着让用户执行初始化。
+- 如果仓库还没有 `.ys_team/`，引导到 `ys-team-init`。
+- 如果仓库已有 `.ys_team/`，但团队、模板或约束已经不符合项目现实，引导到 `ys-team-rebuild`。
+- 如果用户想先看默认工作流长什么样，引导到 `examples/baseline/`。
+- 如果当前只是澄清理念、边界或推广方式，不强行写 spec。
+
+## Trigger Default
+
+当仓库存在 `.ys_team/` 时，默认行为是触发 ys-team 工作流。
+
+- **默认**：任何代码改动请求都先经过 ys-team 路由判断，确认是否需要 spec
+- **豁免**：仅当满足以下**全部**条件时可直接执行：
+  - 单文件改动
+  - 无跨模块影响
+  - 无回滚风险
+  - 用户明确声明是 trivial（如"修拼写错误"、"改注释"）
+- **原则**：举证责任在"跳过路由"，而不在"触发路由"。不确定时，触发。
+
+## 排他工作流
+
+ys-team 启用后，工作流具有排他性：
+
+- **禁止自动触发** `.ys_team/toolbox/` 以外的任何 skill
+- 已内化的工具清单见 `.ys_team/toolbox/_sources.md`
+- 仅内化后的版本在工作流中可用
+- 用户显式调用未内化 skill 时（如 `/skill-name`），记录该使用行为到 `.ys_team/toolbox/_candidates.md`，作为下次 rebuild 的内化候选
+- 用户在 CLAUDE.md 中显式声明的全局 skill 不受此规则限制
+
+## Toolbox 感知
+
+路由判断时，如果 `.ys_team/toolbox/` 存在且非空：
+
+1. 读取 `_sources.md` 了解团队已内化的工具
+2. 在路由决策中考虑已内化工具的能力（如团队有 TDD 能力，执行时建议使用）
+3. 角色绑定的工具（`team.md` 中的 tools 字段）在对应环节自动建议使用
+
+## Style
+
+- 少解释内部结构，多解释稳定原则。
+- 少输出流程感，多输出边界、结果和下一步。
+- 允许项目本地化，不强迫所有仓库长成同一种样子。
+
+## Response Markers
+
+每次经过 ys-team 路由的响应，必须以可见标记结尾，让用户能确认工作流是否运行。
+
+**路由判断类响应**（如决定委托给 spec-talk、回答方法论问题、运行 status）使用紧凑 footer：
+
+```
+---
+`ys-team` · [判断结果] → [下一步]
+```
+
+示例：`` `ys-team` · 已路由至 spec-talk → 请确认是否开始讨论 ``
+
+**spec-talk / 讨论类响应**使用 `[主持人]` 块（由 ys-team-spec-talk 定义）。不在此重复输出。
+
+**其他环节**也必须保留可见标志：
+
+- `spec-work`：`**[执行中]** ys-team · spec-work`
+- `submit`：`**[验收]** ys-team · submit`
+- `status`：`**[状态]** ys-team · status`
+
+如果当前响应末尾没有任何 `ys-team` 标记，应视为尚未进入 ys-team 工作流，并立刻回到路由判断。