@heihei0299/matt-skills 3.0.26 → 3.0.28

package/.agents/skills/initialize-project/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: initialize-project
+description: "Initialize a target repository's agent context by deriving stable project facts, updating AGENTS.md with a compact six-part context block, and writing detailed PROJECT.md context."
+disable-model-invocation: true
+---
+
+# Initialize Project
+
+显式调用本 skill，在目标项目根目录初始化或刷新项目上下文。先读取事实，再写文件；不凭目录名、包名或猜测补全项目目标。
+
+## 1. 收集事实
+
+读取能说明项目真实行为的版本化材料：
+
+- `README.md`、现有 `AGENTS.md`、`PROJECT.md`、`CONTEXT.md` 和相关文档
+- `package.json`、其他 manifest、构建/运行配置
+- 根目录和主要源码目录，定位架构边界、入口、关键职责
+- 测试目录、测试配置和 CI 配置，确认测试规则与稳定命令
+
+优先记录稳定且代理需要知道、但不能从一次查找直接得出的事实。不要把完整命令清单、依赖清单、动态路线图或重复的通用规则写进 `PROJECT.md`。若项目用途、范围、入口或六项内容无法从仓库确认，一次性向用户询问缺失事实后再写入。
+
+文档语言跟随目标仓库的主要语言；没有明确语言信号时跟随用户语言。保留现有文档的其他内容。
+
+## 2. 更新 `AGENTS.md`
+
+维护唯一的受管区块，使用以下标记：
+
+```md
+<!-- matt-skills:managed:start -->
+## 项目上下文
+### 架构边界
+见 `PROJECT.md` 的“架构边界”。
+### 仓库地图
+见 `PROJECT.md` 的“仓库地图”。
+### 标准命令
+见 `PROJECT.md` 的“标准命令”。
+### 测试规则
+见 `PROJECT.md` 的“测试规则”。
+### 项目约束
+见 `PROJECT.md` 的“项目约束”。
+### 完成标准
+见 `PROJECT.md` 的“完成标准”。
+<!-- matt-skills:managed:end -->
+```
+
+- 六个 `###` 标题必须按 `架构边界`、`仓库地图`、`标准命令`、`测试规则`、`项目约束`、`完成标准` 顺序出现。
+- 受管区块总行数必须不超过 30 行；只写简要规则或 `PROJECT.md` 指针，详细事实只放 `PROJECT.md`。
+- 已有完整标记区块时原位替换；没有时追加到文件末尾；不得重排、覆盖或改写其他内容。
+- `AGENTS.md` 不存在时，优先复制目标项目的 `template/AGENTS.md`，再追加区块；模板不可用时创建最小 `AGENTS.md`，只包含该区块。
+- 无论项目是否存在 `CLAUDE.md`，初始化状态和项目上下文都固定维护在 `AGENTS.md`。
+
+## 3. 更新 `PROJECT.md`
+
+维护 `PROJECT.md` 专用受管标记（不要与 `AGENTS.md` 的 CLI 受管标记混用）：
+
+```md
+<!-- initialize-project:start -->
+## 项目概览
+### 项目用途
+### 项目范围
+### 主要入口
+### 架构边界
+### 仓库地图
+### 标准命令
+### 测试规则
+### 项目约束
+### 完成标准
+<!-- initialize-project:end -->
+```
+
+将每个标题填成基于仓库事实的详细说明：
+
+- **项目用途**：解决的问题、服务对象和预期结果。
+- **项目范围**：负责的能力，以及仓库明确排除的范围；没有证据就不臆造非目标。
+- **主要入口**：用户入口、应用/包入口和代理应先看的文档或目录。
+- **架构边界**：模块职责、依赖方向、外部系统边界和不可跨越的层次边界。
+- **仓库地图**：关键目录及其职责；只列影响代理决策的稳定目录。
+- **标准命令**：少量最常用且稳定的开发、验证或发布入口；命令的完整来源仍以 manifest 和配置为准。
+- **测试规则**：测试位置、测试层级、命名/运行约定，以及失败时必须保留的证据。
+- **项目约束**：运行时、兼容性、安全、生成文件、依赖或发布方面的明确约束。
+- **完成标准**：实现、验证、文档、工作区或提交范围方面的交付要求。
+
+`PROJECT.md` 不存在时创建标题 `# Project Context` 后写入区块。已存在且含完整标记时只替换标记内内容；已存在但没有标记时在末尾追加区块，不覆盖自由格式内容。若标记不成对，停止写入并报告，避免破坏文档。不得生成空章节、`TBD` 或未经确认的事实。
+
+## 4. 完成检查
+
+写入后确认：
+
+- `AGENTS.md` 区块只有一份，六个标题顺序正确且总行数不超过 30 行。
+- `PROJECT.md` 区块只有一份，九个章节均有事实内容，且其他内容未改变。
+- 第二次运行会原位替换而不是追加重复内容。
+- 只修改目标 `AGENTS.md`/`PROJECT.md` 和本 skill 需要的文件；不创建备份或额外模板资源。

package/README.md

@@ -28,15 +28,16 @@ template/
 
 ## 独有 skill 分发边界
 
-本仓库有 7 个独有（proprietary）skills：
+本仓库有 8 个独有（proprietary）skills：
 
-### 可分发的 5 个
+### 可分发的 6 个
 
 - `tdd-implement`
 - `diagnose-fix`
 - `grill-to-spec`
 - `scaffold-functional-test`
 - `show-me`
+- `initialize-project`
 
 ### 仓库内部的 2 个
 
@@ -50,7 +51,7 @@ repo-local skills 不会通过 `init`、`install`、`sync` 分发到用户项目
 在目标仓库根目录执行：
 
 ```sh
-npx @heihei0299/matt-skills init              # 安装默认 programming skills
+npx @heihei0299/matt-skills init              # 安装默认 workflow skills
 npx @heihei0299/matt-skills init --all       # 安装全部可分发 skills
 ```
 
@@ -64,7 +65,7 @@ npx @heihei0299/matt-skills sync --dry-run --json
 
 `init` 对已有 `AGENTS.md` 始终跳过；已有项目使用 `sync`。默认 `sync` 保留已有 `AGENTS.md` 和项目规则，`--all` 只扩大技能范围。需要显式刷新 `AGENTS.md` 时使用 `sync --refresh-agents`；无受管区块时会先备份为 `AGENTS.md.bak`。`sync` 不删除目标项目的额外文件或自定义 skills。
 
-默认 programming 范围中的 4 个独有 skills 是 `tdd-implement`、`diagnose-fix`、`grill-to-spec`、`show-me`。
+默认 workflow 范围固定为 14 个入口及依赖 skills，包含 `initialize-project`、`setup-matt-pocock-skills`、`wayfinder`、`grill-to-spec`、`grill-with-docs`、`to-spec`、`to-tickets`、`tdd-implement`、`implement`、`handoff`、`grilling`、`domain-modeling`、`tdd` 和 `code-review`；其中默认独有 skills 是 `tdd-implement`、`grill-to-spec`、`initialize-project`。完整可分发集合仍通过 `--all` 获取。
 
 ## CLI
 
@@ -78,7 +79,7 @@ npx @heihei0299/matt-skills check [--all] [--json] [--upstream <url>] [--ref <re
 
 常用选项：
 
-- `--all`：包含全部可分发 skills，默认范围只包含 programming skills；不会隐式刷新 `AGENTS.md`。
+- `--all`：包含全部可分发 skills，默认范围只包含 workflow skills；不会隐式刷新 `AGENTS.md`。
 - `--refresh-agents`：显式刷新目标 `AGENTS.md`；与 `--all`、`--dry-run` 可组合。
 - `--dest <dir>`：指定目标目录。
 - `--tools <list>`：选择 `codex`、`pi`、`opencode` 或 `claude`；项目级 skills 统一写入 `.agents/skills/`，全局安装仍使用各工具目录。

package/bin/cli.js

@@ -15,18 +15,11 @@ import { loadSkillSet } from './skill-config.js';
 
 const SKILLS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '.agents', 'skills');
 const TEMPLATE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'template');
-const ENGINEERING_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'config', 'engineering.json');
-const REQUIRED_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'config', 'required.json');
-let ENGINEERING_SKILLS = null;
-async function loadEngineeringSkills() {
-  if (!ENGINEERING_SKILLS) ENGINEERING_SKILLS = await loadSkillSet(ENGINEERING_PATH, 'engineering');
-  return ENGINEERING_SKILLS;
-}
-
-let REQUIRED_SKILLS = null;
-async function loadRequiredSkills() {
-  if (!REQUIRED_SKILLS) REQUIRED_SKILLS = await loadSkillSet(REQUIRED_PATH, 'required');
-  return REQUIRED_SKILLS;
+const DEFAULT_PATH = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'config', 'default.json');
+let DEFAULT_SKILLS = null;
+async function loadDefaultSkills() {
+  if (!DEFAULT_SKILLS) DEFAULT_SKILLS = await loadSkillSet(DEFAULT_PATH, 'default');
+  return DEFAULT_SKILLS;
 }
 process.stdout.on('error', (err) => {
   if (err.code === 'EPIPE') process.exit(0);
@@ -55,7 +48,7 @@ Usage:
 
 Init options:
   --dest <path>   Target directory (default: current directory)
-  --all           Include all distributable skills; default only default programming skills
+  --all           Include all distributable skills; default only default workflow skills
   --help, -h      Show this help
 提示：已有 AGENTS.md 时 init 始终跳过；需要更新已有项目请使用 sync。
 
@@ -76,7 +69,7 @@ Sync options:
   --help, -h         Show this help
   项目 skills：${PROJECT_SKILL_DIRS}
 
-说明：默认同步默认编程 skill 并保留现有 AGENTS.md；--all 只扩大技能范围。
+说明：默认同步默认 workflow skill 并保留现有 AGENTS.md；--all 只扩大技能范围。
       --refresh-agents 与 --all、--dry-run 可组合；上游检查请使用 check。
 
 提示：matt-skills --help 查看全量
@@ -88,7 +81,7 @@ Usage:
   matt-skills list [--all] [--json]
 
 List options:
-  --all           List all distributable skills (default only default programming skills)
+  --all           List all distributable skills (default only default workflow skills)
   --json          Output as JSON
   --help, -h      Show this help
 
@@ -117,7 +110,7 @@ Usage:
 
 Install options:
   --tools <a,b>   Install for the given tools (codex, pi, opencode, claude); skips tool selection
-  --all           Install all distributable skills (default only default programming); skips skill selection
+  --all           Install all distributable skills (default only default workflow); skips skill selection
   --force         Overwrite existing skills
   --global        Install to the user's global skill directories
   --project       Install to project skill directories (default)
@@ -160,8 +153,7 @@ async function listSkillNames({ onlyProgramming = false } = {}) {
   return resolveSkillNames({
     availableNames: await listAvailableSkillNames(),
     mode: onlyProgramming ? 'default' : 'all',
-    engineering: onlyProgramming ? await loadEngineeringSkills() : [],
-    required: onlyProgramming ? await loadRequiredSkills() : [],
+    defaults: onlyProgramming ? await loadDefaultSkills() : [],
   });
 }
 
@@ -410,17 +402,17 @@ async function initCommand({ dest, all }) {
     installed = entries.filter((e) => e.isDirectory() && !e.name.endsWith('.bak') && e.name !== '.git' && e.name !== 'skill-creator' && !isRepoLocalSkill(e.name)).length;
   } catch {}
   const allSkillsFull = await listSkills({ onlyProgramming: false });
-  const programmingSkills = await listSkills({ onlyProgramming: true });
-  const programmingCount = programmingSkills.length;
+  const defaultSkills = await listSkills({ onlyProgramming: true });
+  const defaultCount = defaultSkills.length;
   const upstreamFull = allSkillsFull.filter((s) => !PROPRIETARY_SKILLS.has(s.name)).length;
-  const upstreamProg = programmingSkills.filter((s) => !PROPRIETARY_SKILLS.has(s.name)).length;
-  const displayTotal = onlyProgramming ? programmingCount : allSkillsFull.length;
-  const displayUpstream = onlyProgramming ? upstreamProg : upstreamFull;
+  const upstreamDefault = defaultSkills.filter((s) => !PROPRIETARY_SKILLS.has(s.name)).length;
+  const displayTotal = onlyProgramming ? defaultCount : allSkillsFull.length;
+  const displayUpstream = onlyProgramming ? upstreamDefault : upstreamFull;
   if (path.resolve(skillsDir) === path.resolve(SKILLS_DIR)) {
-    process.stdout.write(`技能：已装 ${installed}、跳过 0（可分发 ${allSkillsFull.length}，含上游 ${upstreamFull}；默认编程 ${programmingCount}，含上游 ${upstreamProg}）\n`);
+    process.stdout.write(`技能：已装 ${installed}、跳过 0（可分发 ${allSkillsFull.length}，含上游 ${upstreamFull}；默认 workflow ${defaultCount}，含上游 ${upstreamDefault}）\n`);
   } else {
     if (onlyProgramming) {
-      process.stdout.write(`技能：已装 ${installed}（默认编程 ${displayTotal}，含上游 ${displayUpstream}；可分发 ${allSkillsFull.length}，含上游 ${upstreamFull}）\n`);
+      process.stdout.write(`技能：已装 ${installed}（默认 workflow ${displayTotal}，含上游 ${displayUpstream}；可分发 ${allSkillsFull.length}，含上游 ${upstreamFull}）\n`);
     } else {
       process.stdout.write(`技能：已装 ${installed}（可分发 ${displayTotal}，含上游 ${displayUpstream}）\n`);
     }
@@ -454,7 +446,7 @@ async function compareDryRunTrees(target, stage) {
 function formatTargetComparison({ target, result, onlyProgramming, refreshAgents }) {
   const lines = [
     `目标: ${target}`,
-    `范围: ${onlyProgramming ? '默认编程' : '全部可分发'}${refreshAgents ? '；刷新 AGENTS.md' : ''}`,
+    `范围: ${onlyProgramming ? '默认 workflow' : '全部可分发'}${refreshAgents ? '；刷新 AGENTS.md' : ''}`,
     '',
   ];
   const totalDiff = result.added.length + result.updated.length + result.removed.length;
@@ -635,7 +627,7 @@ async function syncCommand({ dest, all, dryRun, json, refreshAgents, quiet = fal
   if (preservedRepoLocal.length) {
     output(`迁移提示：${preservedRepoLocal.join(', ')} 已不再分发，现有副本已保留\n`);
   }
-  const modeLabel = onlyProgramming ? '默认编程' : '全部可分发';
+  const modeLabel = onlyProgramming ? '默认 workflow' : '全部可分发';
   output(`技能：新增 ${installed}、更新 ${updated}（${modeLabel} ${allSkills.length}）\n`);
   output(`目标路径：${target}\n`);
 }

package/bin/skill-selection.js

@@ -1,25 +1,16 @@
-import {
-  DEFAULT_PROPRIETARY_SKILLS,
-  isDistributableSkill,
-} from './skill-boundaries.js';
+import { isDistributableSkill } from './skill-boundaries.js';
 
 function asSet(value) {
   return value instanceof Set ? new Set(value) : new Set(value ?? []);
 }
 
-export function resolveSkillNames({ availableNames, mode = 'default', engineering, required }) {
+export function resolveSkillNames({ availableNames, mode = 'default', defaults }) {
   if (mode !== 'default' && mode !== 'all') {
     throw new Error(`unknown skill selection mode: ${mode}`);
   }
 
   const available = asSet(availableNames);
-  const candidates = mode === 'all'
-    ? available
-    : new Set([
-      ...asSet(engineering),
-      ...asSet(required),
-      ...DEFAULT_PROPRIETARY_SKILLS,
-    ]);
+  const candidates = mode === 'all' ? available : asSet(defaults);
 
   return [...candidates]
     .filter((name) => available.has(name) && isDistributableSkill(name, available))

package/config/default.json

@@ -0,0 +1,16 @@
+[
+  "code-review",
+  "domain-modeling",
+  "grill-to-spec",
+  "grill-with-docs",
+  "grilling",
+  "handoff",
+  "implement",
+  "initialize-project",
+  "setup-matt-pocock-skills",
+  "tdd",
+  "tdd-implement",
+  "to-spec",
+  "to-tickets",
+  "wayfinder"
+]

package/config/engineering.json

@@ -16,5 +16,6 @@
   "to-tickets",
   "triage",
   "wayfinder",
-  "wizard"
+  "wizard",
+  "initialize-project"
 ]

package/config/proprietary.json

@@ -6,14 +6,16 @@
     "diagnose-fix",
     "commit-check",
     "scaffold-functional-test",
-    "show-me"
+    "show-me",
+    "initialize-project"
   ],
   "distributable": [
     "tdd-implement",
     "diagnose-fix",
     "grill-to-spec",
     "scaffold-functional-test",
-    "show-me"
+    "show-me",
+    "initialize-project"
   ],
   "repoLocal": [
     "ci-guard",
@@ -21,8 +23,7 @@
   ],
   "default": [
     "tdd-implement",
-    "diagnose-fix",
     "grill-to-spec",
-    "show-me"
+    "initialize-project"
   ]
 }

package/config/required.json

@@ -1,5 +1,4 @@
 [
   "grilling",
-  "grill-me",
   "handoff"
 ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heihei0299/matt-skills",
-  "version": "3.0.26",
+  "version": "3.0.28",
   "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
   "type": "module",
   "bin": {
@@ -13,6 +13,7 @@
     "scripts/sync-upstream.js",
     "scripts/codex-smoke.js",
     "config/proprietary.json",
+    "config/default.json",
     "config/engineering.json",
     "config/required.json",
     "README.md"