adspecs 0.1.19 → 0.1.21

package/scripts/sync-version.js

@@ -1,105 +1,105 @@
-#!/usr/bin/env node
-'use strict';
-
-/**
- * 版本同步脚本
- *
- * 在 `npm version <type>` 时自动执行（通过 preversion 钩子）。
- * 将 package.json 的新版本同步到三套插件清单文件：
- *   - .claude-plugin/plugin.json
- *   - .claude-plugin/marketplace.json
- *   - .qoder-plugin/plugin.json
- *
- * 也可手动运行：`npm run sync-version`
- *
- * 使用流程：
- *   npm version patch    # 自动：升 package.json 版本 → 同步到其他清单 → git commit
- *   npm version minor
- *   npm version major
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const ROOT = path.resolve(__dirname, '..');
-
-function readJson(relativePath) {
-  const fullPath = path.join(ROOT, relativePath);
-  if (!fs.existsSync(fullPath)) {
-    return null;
-  }
-  return JSON.parse(fs.readFileSync(fullPath, 'utf8'));
-}
-
-function writeJson(relativePath, data) {
-  const fullPath = path.join(ROOT, relativePath);
-  fs.writeFileSync(fullPath, JSON.stringify(data, null, 2) + '\n', 'utf8');
-}
-
-function main() {
-  const pkg = readJson('package.json');
-  if (!pkg) {
-    console.error('❌ 未找到 package.json');
-    process.exit(1);
-  }
-
-  const newVersion = pkg.version;
-  console.log(`🔧 同步版本 ${newVersion} 到插件清单...`);
-
-  const updated = [];
-
-  // 1. .claude-plugin/plugin.json
-  const claudePlugin = readJson('.claude-plugin/plugin.json');
-  if (claudePlugin && claudePlugin.version !== newVersion) {
-    const old = claudePlugin.version;
-    claudePlugin.version = newVersion;
-    writeJson('.claude-plugin/plugin.json', claudePlugin);
-    updated.push(`.claude-plugin/plugin.json (${old} → ${newVersion})`);
-  }
-
-  // 2. .claude-plugin/marketplace.json
-  const marketplace = readJson('.claude-plugin/marketplace.json');
-  if (marketplace && marketplace.plugins && marketplace.plugins[0]) {
-    const old = marketplace.plugins[0].version;
-    if (old !== newVersion) {
-      marketplace.plugins[0].version = newVersion;
-      writeJson('.claude-plugin/marketplace.json', marketplace);
-      updated.push(`.claude-plugin/marketplace.json (${old} → ${newVersion})`);
-    }
-  }
-
-  // 3. .qoder-plugin/plugin.json — 始终与 package.json 保持版本一致
-  const qoderPlugin = readJson('.qoder-plugin/plugin.json');
-  if (qoderPlugin && qoderPlugin.version !== newVersion) {
-    const old = qoderPlugin.version;
-    qoderPlugin.version = newVersion;
-    writeJson('.qoder-plugin/plugin.json', qoderPlugin);
-    updated.push(`.qoder-plugin/plugin.json (${old} → ${newVersion})`);
-  }
-
-  if (updated.length === 0) {
-    console.log('✅ 所有清单版本已一致，无需更新');
-  } else {
-    console.log(`✅ 已更新 ${updated.length} 个清单文件：`);
-    for (const u of updated) {
-      console.log(`   - ${u}`);
-    }
-  }
-
-  // 4. 提示 git add（preversion 阶段，文件变更会在 npm version 后一起提交）
-  if (updated.length > 0) {
-    try {
-      const { execSync } = require('child_process');
-      // 将修改的清单文件加入 git staging（npm version 会自动 commit）
-      const filesToAdd = updated
-        .map((u) => u.split(' ')[0])
-        .join(' ');
-      execSync(`git add ${filesToAdd}`, { stdio: 'ignore', cwd: ROOT });
-      console.log('   (已 git add 修改的清单文件)');
-    } catch {
-      // git add 失败不影响流程
-    }
-  }
-}
-
-main();
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * 版本同步脚本
+ *
+ * 在 `npm version <type>` 时自动执行（通过 preversion 钩子）。
+ * 将 package.json 的新版本同步到三套插件清单文件：
+ *   - .claude-plugin/plugin.json
+ *   - .claude-plugin/marketplace.json
+ *   - .qoder-plugin/plugin.json
+ *
+ * 也可手动运行：`npm run sync-version`
+ *
+ * 使用流程：
+ *   npm version patch    # 自动：升 package.json 版本 → 同步到其他清单 → git commit
+ *   npm version minor
+ *   npm version major
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+
+function readJson(relativePath) {
+  const fullPath = path.join(ROOT, relativePath);
+  if (!fs.existsSync(fullPath)) {
+    return null;
+  }
+  return JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+}
+
+function writeJson(relativePath, data) {
+  const fullPath = path.join(ROOT, relativePath);
+  fs.writeFileSync(fullPath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+
+function main() {
+  const pkg = readJson('package.json');
+  if (!pkg) {
+    console.error('❌ 未找到 package.json');
+    process.exit(1);
+  }
+
+  const newVersion = pkg.version;
+  console.log(`🔧 同步版本 ${newVersion} 到插件清单...`);
+
+  const updated = [];
+
+  // 1. .claude-plugin/plugin.json
+  const claudePlugin = readJson('.claude-plugin/plugin.json');
+  if (claudePlugin && claudePlugin.version !== newVersion) {
+    const old = claudePlugin.version;
+    claudePlugin.version = newVersion;
+    writeJson('.claude-plugin/plugin.json', claudePlugin);
+    updated.push(`.claude-plugin/plugin.json (${old} → ${newVersion})`);
+  }
+
+  // 2. .claude-plugin/marketplace.json
+  const marketplace = readJson('.claude-plugin/marketplace.json');
+  if (marketplace && marketplace.plugins && marketplace.plugins[0]) {
+    const old = marketplace.plugins[0].version;
+    if (old !== newVersion) {
+      marketplace.plugins[0].version = newVersion;
+      writeJson('.claude-plugin/marketplace.json', marketplace);
+      updated.push(`.claude-plugin/marketplace.json (${old} → ${newVersion})`);
+    }
+  }
+
+  // 3. .qoder-plugin/plugin.json — 始终与 package.json 保持版本一致
+  const qoderPlugin = readJson('.qoder-plugin/plugin.json');
+  if (qoderPlugin && qoderPlugin.version !== newVersion) {
+    const old = qoderPlugin.version;
+    qoderPlugin.version = newVersion;
+    writeJson('.qoder-plugin/plugin.json', qoderPlugin);
+    updated.push(`.qoder-plugin/plugin.json (${old} → ${newVersion})`);
+  }
+
+  if (updated.length === 0) {
+    console.log('✅ 所有清单版本已一致，无需更新');
+  } else {
+    console.log(`✅ 已更新 ${updated.length} 个清单文件：`);
+    for (const u of updated) {
+      console.log(`   - ${u}`);
+    }
+  }
+
+  // 4. 提示 git add（preversion 阶段，文件变更会在 npm version 后一起提交）
+  if (updated.length > 0) {
+    try {
+      const { execSync } = require('child_process');
+      // 将修改的清单文件加入 git staging（npm version 会自动 commit）
+      const filesToAdd = updated
+        .map((u) => u.split(' ')[0])
+        .join(' ');
+      execSync(`git add ${filesToAdd}`, { stdio: 'ignore', cwd: ROOT });
+      console.log('   (已 git add 修改的清单文件)');
+    } catch {
+      // git add 失败不影响流程
+    }
+  }
+}
+
+main();

package/skills/.claude/.wiki-update-queue

@@ -1,26 +1,26 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/skills/adspecs-constitution/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: "adspecs-constitution"
+description: "根据交互式输入或提供的原则输入创建或更新项目章程，确保所有依赖模板保持同步。"
+argument-hint: "项目章程的原则或价值观"
+compatibility: "需要 adspecs 项目结构，包含 .adspecs/ 目录"
+metadata:
+  author: "adspecs"
+  source: "templates/commands/constitution.md"
+user-invocable: true
+disable-model-invocation: false
+---
+
+
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+**必须** 在继续之前考虑用户输入（如果非空）。
+
+## 执行前检查
+
+**检查扩展钩子（章程更新前）**:
+- 检查项目根目录是否存在 `.adspecs/extensions.yml`。
+- 如果存在，读取它并查找 `hooks.before_constitution` 下的条目。
+- 如果 YAML 无法解析或无效，静默跳过钩子检查并继续正常执行。
+- 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。
+- 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式：
+  - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。
+  - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。
+- 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/adspecs-git-commit`。
+- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
+  - **可选钩子** (`optional: true`):
+    ```
+    ## 扩展钩子
+
+    **可选前置钩子**: {extension}
+    命令: `/{command}`
+    描述: {description}
+
+    提示: {prompt}
+    执行: `/{command}`
+    ```
+  - **必选钩子** (`optional: false`):
+    ```
+    ## 扩展钩子
+
+    **自动前置钩子**: {extension}
+    执行: `/{command}`
+    EXECUTE_COMMAND: {command}
+
+    等待钩子命令结果后再继续执行。
+    ```
+- 如果没有注册钩子或 `.adspecs/extensions.yml` 不存在，静默跳过。
+
+## 执行流程
+
+你需要更新位于 `.adspecs/memory/constitution.md` 的项目章程。该文件是一个模板，包含方括号形式的占位符标记（例如 `[PROJECT_NAME]`、`[PRINCIPLE_1_NAME]`）。你的任务是：（a）收集/推导具体值，（b）精确填充模板，（c）将任何修订传播到依赖产物中。
+
+**注意**: 如果 `.adspecs/memory/constitution.md` 尚不存在，它应该已在项目初始化阶段从 `.adspecs/templates/constitution-template.md` 模板复制而来。如果缺失，请先复制模板。
+
+按以下执行流程操作：
+
+1. 加载现有章程 `.adspecs/memory/constitution.md`。
+   - 识别所有形如 `[全大写字母标识符]` 的占位符标记。
+   **重要**: 用户要求的原则数量可能少于或多于模板中的数量。如果指定了数量，请遵循该数量——按通用模板结构处理。你需要相应地更新文档。
+
+2. 收集/推导占位符的值：
+   - 如果用户输入（对话）提供了值，直接使用该值。
+   - 否则从现有仓库上下文推断（README、文档、先前的章程版本（如果嵌入））。
+   - 对于治理日期：`RATIFICATION_DATE` 为最初采纳日期（如果未知则询问或标记 TODO），`LAST_AMENDED_DATE` 为今天（如果做了更改），否则保留之前的日期。
+   - `CONSTITUTION_VERSION` 必须按语义化版本规则递增：
+     - MAJOR（主版本）: 向后不兼容的治理/原则删除或重新定义。
+     - MINOR（次版本）: 新增原则/章节或实质性扩展指引。
+     - PATCH（补丁版本）: 澄清、措辞、错别字修复、非语义性改进。
+   - 如果版本递增类型存在歧义，在最终确定之前先提出推理说明。
+
+3. 草拟更新后的章程内容：
+   - 将每个占位符替换为具体文本（不遗留方括号标记，除非是项目有意选择暂不定义的模板槽位——需对任何保留项进行明确说明）。
+   - 保留标题层级结构；注释在替换后可以删除，除非它们仍然提供有 clarifying 指引价值。
+   - 确保每个原则章节包含：简洁的名称行、描述不可协商规则的段落（或项目符号列表）、以及如果不显然则提供明确的理由。
+   - 确保治理章节列出修订程序、版本策略和合规审查要求。
+
+4. 一致性传播检查清单（将先前检查清单转化为主动验证）：
+   - 读取 `.adspecs/templates/plan-template.md`，确保任何"章程检查"或规则与更新后的原则一致。
+   - 读取 `.adspecs/templates/spec-template.md`，检查范围/需求对齐——如果章程添加/删除了必填章节或约束，则更新。
+   - 读取 `.adspecs/templates/tasks-template.md`，确保任务分类反映新增或删除的原则驱动任务类型（例如可观测性、版本管理、测试纪律）。
+   - 读取 `.adspecs/templates/commands/*.md` 中的每个命令文件（包括本文件），验证当需要通用指引时，不存在过时的引用（仅针对特定 agent 的名称如 CLAUDE）。
+   - 读取任何运行时指引文档（例如 `README.md`、`docs/quickstart.md`，或存在的 agent 特定指引文件）。更新引用已变更原则的内容。
+
+5. 生成同步影响报告（在更新后以 HTML 注释形式.prepend.到章程文件顶部）：
+   - 版本变更: 旧版本 → 新版本
+   - 已修改的原则列表（如果重命名，标注旧标题 → 新标题）
+   - 新增章节
+   - 删除章节
+   - 需要更新的模板（✅ 已更新 / ⚠ 待处理）及文件路径
+   - 如果有任何占位符有意延迟处理，列出后续 TODO。
+
+6. 最终输出前的验证：
+   - 无遗留的未解释方括号标记。
+   - 版本行与报告一致。
+   - 日期使用 ISO 格式 YYYY-MM-DD。
+   - 原则是声明性的、可测试的，不含模糊语言（"应该" → 在适当位置替换为 MUST/SHOULD 理由）。
+
+7. 将完成的章程写回 `.adspecs/memory/constitution.md`（覆盖）。
+
+8. 向用户输出最终总结，包含：
+   - 新版本及递增理由。
+   - 任何标记为需要手动跟进的文件。
+   - 建议的提交消息（例如 `docs: 修订章程至 vX.Y.Z（原则新增 + 治理更新）`）。
+
+格式与风格要求：
+
+- 使用模板中完全一致的 Markdown 标题（不要降级/升级层级）。
+- 长理由行可换行以保持可读性（理想 <100 字符），但不强制硬性截断。
+- 章节之间保留一个空行。
+- 避免尾随空白。
+
+如果用户提供部分更新（例如仅修订一个原则），仍需执行验证和版本决策步骤。
+
+如果关键信息缺失（例如批准日期确实未知），插入 `TODO(<FIELD_NAME>): 说明` 并在同步影响报告的延迟项中列出。
+
+不要创建新模板；始终操作现有的 `.adspecs/memory/constitution.md` 文件。
+
+## 执行后检查
+
+**检查扩展钩子（章程更新后）**:
+检查项目根目录是否存在 `.adspecs/extensions.yml`。
+- 如果存在，读取它并查找 `hooks.after_constitution` 下的条目。
+- 如果 YAML 无法解析或无效，静默跳过钩子检查并继续正常执行。
+- 过滤掉 `enabled` 明确为 `false` 的钩子。没有 `enabled` 字段的钩子默认视为启用。
+- 对于每个剩余的钩子，**不要** 尝试解释或评估钩子的 `condition` 表达式：
+  - 如果钩子没有 `condition` 字段，或为空/null，视为可执行。
+  - 如果钩子定义了非空的 `condition`，跳过该钩子，将条件评估留给 HookExecutor 实现。
+- 从钩子命令名构造斜杠命令时，将点号（`.`）替换为连字符（`-`）。例如：`adspecs.git.commit` → `/adspecs-git-commit`。
+- 对于每个可执行钩子，根据其 `optional` 标志输出以下内容：
+  - **可选钩子** (`optional: true`):
+    ```
+    ## 扩展钩子
+
+    **可选钩子**: {extension}
+    命令: `/{command}`
+    描述: {description}
+
+    提示: {prompt}
+    执行: `/{command}`
+    ```
+  - **必选钩子** (`optional: false`):
+    ```
+    ## 扩展钩子
+
+    **自动钩子**: {extension}
+    执行: `/{command}`
+    EXECUTE_COMMAND: {command}
+    ```
+- 如果没有注册钩子或 `.adspecs/extensions.yml` 不存在，静默跳过。