@zhuan-ai/zhuanspec 1.3.0

package/dist/core/templates/slash-command-templates.d.ts

@@ -0,0 +1,4 @@
+export type SlashCommandId = 'proposal' | 'apply' | 'archive';
+export declare const slashCommandBodies: Record<SlashCommandId, string>;
+export declare function getSlashCommandBody(id: SlashCommandId): string;
+//# sourceMappingURL=slash-command-templates.d.ts.map

package/dist/core/templates/slash-command-templates.js

@@ -0,0 +1,81 @@
+const baseGuardrails = `**约束条件**
+- 优先采用简单、最小化的实现，仅在请求或明确需要时添加复杂性。
+- 将更改严格限制在请求的结果范围内。
+- 如果需要额外的 ZhuanSpec 约定或澄清，请参考 \`zhuanspec/AGENTS.md\`（位于 \`zhuanspec/\` 目录内 - 如果看不到，请运行 \`ls zhuanspec\` 或 \`zhuanspec update\`）。`;
+const proposalGuardrails = `${baseGuardrails}\n- **强制澄清要求**：在创建任何提案文件之前，必须首先分析用户请求，识别所有不确定或模糊的方面（范围、技术选择、优先级、验收标准等）。如果发现任何模糊之处，必须停止并使用**选项式交互**（如 \`AskQuestion\` 工具）提问，获得明确答复后才能继续。严禁在不确定的情况下自行推测、假设或创建提案。严禁要求用户手动输入大段文字来回答澄清问题。
+- 识别任何模糊或歧义的细节，使用带预设选项的选择题在编辑文件之前询问必要的后续问题。
+- 在提案阶段不要编写任何代码。仅创建设计文档（proposal.md、tasks.md、design.md 和规范增量）。实施在批准后的应用阶段进行。`;
+const proposalSteps = `**步骤**
+0. 审查 \`zhuanspec/project.md\`，运行 \`zhuanspec list\` 和 \`zhuanspec list --specs\`，并检查相关代码或文档（例如，通过 \`rg\`/\`ls\`）以将提案建立在当前行为基础上；注意任何需要澄清的空白。
+1. **强制澄清检查（必须首先执行，不可跳过）**：
+   - 仔细分析用户请求，识别所有不确定或模糊的方面：
+     * 范围是否明确？（边界、包含/排除的内容）
+     * 技术选择是否明确？（框架、库、架构模式）
+     * 优先级是否明确？（如果有多个需求）
+     * 验收标准是否明确？（如何判断完成）
+     * 上下文信息是否充分？（背景、约束、依赖）
+     * 实现细节是否明确？（如何获取数据、如何处理错误、如何优化性能）
+     * 数据获取来源是否明确？（从数据库、API、文件、外部服务、历史逻辑复用）
+     * 服务分层是否明确？（前端、后端、数据库、API、服务、4层架构、3层架构、2层架构、领域模型）
+     * 依赖关系是否明确？（依赖哪些服务、依赖哪些库、依赖哪些组件）
+     * 其他不明确？（其他不明确的情况）
+   - 如果发现任何模糊之处，必须停止并使用**选项式交互**提问：
+     * 使用编辑器的结构化问答工具（如 \`AskQuestion\`），将每个问题转化为带 2-5 个预设选项的选择题
+     * 每个问题末尾包含"其他"选项作为兜底
+     * 尽量将多个问题合并到一次交互中一次性展示
+     * 必须等待用户选择答案，不能继续
+     * **严禁**要求用户手动输入大段文字来回答
+   - 如果用户选择"其他"，再针对该问题追问（仍优先使用选项式）
+   - **严禁**在不确定的情况下自行推测、假设或创建提案文件
+   - 只有在所有模糊点都明确后，才能继续后续步骤
+2. 选择一个唯一的动词开头的 \`change-id\`，并在 \`zhuanspec/changes/<id>/\` 下搭建 \`proposal.md\`、\`tasks.md\` 和 \`design.md\`（需要时）。
+3. 将变更映射为具体的功能或要求，将多范围的工作分解为具有明确关系和顺序的不同规范增量。
+4. 当解决方案跨越多个系统、引入新模式或在提交规范之前需要权衡讨论时，在 \`design.md\` 中捕获架构推理。
+5. 在 \`changes/<id>/specs/<capability>/spec.md\` 中起草规范增量（每个功能一个文件夹），使用 \`## ADDED|MODIFIED|REMOVED Requirements\`，每个要求至少包含一个 \`#### Scenario:\`，并在相关时交叉引用相关功能。
+6. **发现可用 Skill 并创建 tasks.md**：
+   - 运行 \`zhuanspec skills list --json\` 获取当前环境中可用的 skill 列表及其 description
+   - 在 \`proposal.md\` 的 **Skill Mapping** 段中基于 skill description 进行语义匹配：
+     - 仔细阅读每个 skill 的 description，理解其具体功能和适用场景
+     - 只有当实现区域的实际功能与 skill description 明确匹配时才关联
+     - 简单的代码修改（如枚举值增删）应匹配通用编码规范 skill，而非架构级 skill
+     - 避免仅因模块名称或文件路径中的关键词而错误匹配
+     - 在表格中说明匹配理由
+   - 将 \`tasks.md\` 起草为有序的小型、可验证工作项列表
+   - 使用 \`@skill:<real-skill-name>\` 标注与 skill 匹配的任务（支持多个：\`@skill:name1,name2\`）
+   - 仅当 skill 明确匹配任务时才标注，没有匹配的 skill 可省略标签
+7. 使用 \`zhuanspec validate <id> --strict\` 进行验证，并在分享提案之前解决所有问题。`;
+const proposalReferences = `**参考**
+- 当验证失败时，使用 \`zhuanspec show <id> --json --deltas-only\` 或 \`zhuanspec show <spec> --type spec\` 检查详细信息。
+- 在编写新要求之前，使用 \`rg -n "Requirement:|Scenario:" zhuanspec/specs\` 搜索现有要求。
+- 使用 \`rg <keyword>\`、\`ls\` 或直接文件读取探索代码库，以便提案与当前实现现实保持一致。`;
+const applySteps = `**步骤**
+将这些步骤作为待办事项跟踪，逐一完成。
+1. 阅读 \`changes/<id>/proposal.md\`、\`design.md\`（如果存在）和 \`tasks.md\` 以确认范围和验收标准。
+2. 按顺序处理任务，保持编辑最小化并专注于请求的变更。如果任务标注了 \`@skill:<skill-name>\`，直接调用对应 skill 获取指导后再实施。
+3. 在更新状态之前确认完成 - 确保 \`tasks.md\` 中的每个项目都已完成。
+4. 所有工作完成后更新清单，以便每个任务都标记为 \`- [x]\` 并反映实际情况。
+5. 需要额外上下文时，参考 \`zhuanspec list\` 或 \`zhuanspec show <item>\`。`;
+const applyReferences = `**参考**
+- 如果在实施过程中需要提案的额外上下文，请使用 \`zhuanspec show <id> --json --deltas-only\`。`;
+const archiveSteps = `**步骤**
+1. 确定要归档的变更 ID：
+   - 如果此提示已包含特定的变更 ID（例如在由斜杠命令参数填充的 \`<ChangeId>\` 块内），请在修剪空白后使用该值。
+   - 如果对话中松散地引用了变更（例如通过标题或摘要），运行 \`zhuanspec list\` 以显示可能的 ID，分享相关候选，并确认用户意图是哪一个。
+   - 否则，审查对话，运行 \`zhuanspec list\`，并询问用户要归档哪个变更；在继续之前等待确认的变更 ID。
+   - 如果您仍然无法识别单个变更 ID，请停止并告诉用户您还无法归档任何内容。
+2. 通过运行 \`zhuanspec list\`（或 \`zhuanspec show <id>\`）验证变更 ID，如果变更缺失、已归档或尚未准备好归档，则停止。
+3. 运行 \`zhuanspec archive <id> --yes\`，以便 CLI 移动变更并应用规范更新，无需提示（仅对仅工具类工作使用 \`--skip-specs\`）。
+4. 审查命令输出以确认目标规范已更新，并且变更已进入 \`changes/archive/\`。
+5. 使用 \`zhuanspec validate --strict\` 进行验证，如果看起来有问题，使用 \`zhuanspec show <id>\` 进行检查。`;
+const archiveReferences = `**参考**
+- 在归档之前使用 \`zhuanspec list\` 确认变更 ID。
+- 使用 \`zhuanspec list --specs\` 检查刷新的规范，并在移交之前解决任何验证问题。`;
+export const slashCommandBodies = {
+    proposal: [proposalGuardrails, proposalSteps, proposalReferences].join('\n\n'),
+    apply: [baseGuardrails, applySteps, applyReferences].join('\n\n'),
+    archive: [baseGuardrails, archiveSteps, archiveReferences].join('\n\n')
+};
+export function getSlashCommandBody(id) {
+    return slashCommandBodies[id];
+}
+//# sourceMappingURL=slash-command-templates.js.map

package/dist/core/update.d.ts

@@ -0,0 +1,4 @@
+export declare class UpdateCommand {
+    execute(projectPath: string): Promise<void>;
+}
+//# sourceMappingURL=update.d.ts.map

package/dist/core/update.js

@@ -0,0 +1,88 @@
+import path from 'path';
+import { FileSystemUtils } from '../utils/file-system.js';
+import { ZHUANSPEC_DIR_NAME } from './config.js';
+import { ToolRegistry } from './configurators/registry.js';
+import { SlashCommandRegistry } from './configurators/slash/registry.js';
+import { agentsTemplate } from './templates/agents-template.js';
+export class UpdateCommand {
+    async execute(projectPath) {
+        const resolvedProjectPath = path.resolve(projectPath);
+        const zhuanspecDirName = ZHUANSPEC_DIR_NAME;
+        const zhuanspecPath = path.join(resolvedProjectPath, zhuanspecDirName);
+        // 1. Check zhuanspec directory exists
+        if (!await FileSystemUtils.directoryExists(zhuanspecPath)) {
+            throw new Error(`未找到 ZhuanSpec 目录。请先运行 'zhuanspec init'。`);
+        }
+        // 2. Update AGENTS.md (full replacement)
+        const agentsPath = path.join(zhuanspecPath, 'AGENTS.md');
+        await FileSystemUtils.writeFile(agentsPath, agentsTemplate);
+        // 3. Update existing AI tool configuration files only
+        const configurators = ToolRegistry.getAll();
+        const slashConfigurators = SlashCommandRegistry.getAll();
+        const updatedFiles = [];
+        const createdFiles = [];
+        const failedFiles = [];
+        const updatedSlashFiles = [];
+        const failedSlashTools = [];
+        for (const configurator of configurators) {
+            const configFilePath = path.join(resolvedProjectPath, configurator.configFileName);
+            const fileExists = await FileSystemUtils.fileExists(configFilePath);
+            const shouldConfigure = fileExists || configurator.configFileName === 'AGENTS.md';
+            if (!shouldConfigure) {
+                continue;
+            }
+            try {
+                if (fileExists && !await FileSystemUtils.canWriteFile(configFilePath)) {
+                    throw new Error(`权限不足，无法修改 ${configurator.configFileName}`);
+                }
+                await configurator.configure(resolvedProjectPath, zhuanspecPath);
+                updatedFiles.push(configurator.configFileName);
+                if (!fileExists) {
+                    createdFiles.push(configurator.configFileName);
+                }
+            }
+            catch (error) {
+                failedFiles.push(configurator.configFileName);
+                console.error(`更新 ${configurator.configFileName} 失败：${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        for (const slashConfigurator of slashConfigurators) {
+            if (!slashConfigurator.isAvailable) {
+                continue;
+            }
+            try {
+                const updated = await slashConfigurator.updateExisting(resolvedProjectPath, zhuanspecPath);
+                updatedSlashFiles.push(...updated);
+            }
+            catch (error) {
+                failedSlashTools.push(slashConfigurator.toolId);
+                console.error(`更新 ${slashConfigurator.toolId} 的斜杠命令失败：${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        const summaryParts = [];
+        const instructionFiles = ['zhuanspec/AGENTS.md'];
+        if (updatedFiles.includes('AGENTS.md')) {
+            instructionFiles.push(createdFiles.includes('AGENTS.md') ? 'AGENTS.md (created)' : 'AGENTS.md');
+        }
+        summaryParts.push(`已更新 ZhuanSpec 说明（${instructionFiles.join(', ')}）`);
+        const aiToolFiles = updatedFiles.filter((file) => file !== 'AGENTS.md');
+        if (aiToolFiles.length > 0) {
+            summaryParts.push(`已更新 AI 工具文件：${aiToolFiles.join(', ')}`);
+        }
+        if (updatedSlashFiles.length > 0) {
+            // Normalize to forward slashes for cross-platform log consistency
+            const normalized = updatedSlashFiles.map((p) => FileSystemUtils.toPosixPath(p));
+            summaryParts.push(`已更新斜杠命令：${normalized.join(', ')}`);
+        }
+        const failedItems = [
+            ...failedFiles,
+            ...failedSlashTools.map((toolId) => `斜杠命令刷新（${toolId}）`),
+        ];
+        if (failedItems.length > 0) {
+            summaryParts.push(`更新失败：${failedItems.join(', ')}`);
+        }
+        console.log(summaryParts.join(' | '));
+        // No additional notes
+    }
+}
+//# sourceMappingURL=update.js.map

package/dist/core/validation/constants.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Validation threshold constants
+ */
+export declare const MIN_WHY_SECTION_LENGTH = 50;
+export declare const MIN_PURPOSE_LENGTH = 50;
+export declare const MAX_WHY_SECTION_LENGTH = 1000;
+export declare const MAX_REQUIREMENT_TEXT_LENGTH = 500;
+export declare const MAX_DELTAS_PER_CHANGE = 10;
+export declare const VALIDATION_MESSAGES: {
+    readonly SCENARIO_EMPTY: "Scenario text cannot be empty";
+    readonly REQUIREMENT_EMPTY: "Requirement text cannot be empty";
+    readonly REQUIREMENT_NO_SHALL: "Requirement must contain SHALL or MUST keyword";
+    readonly REQUIREMENT_NO_SCENARIOS: "Requirement must have at least one scenario";
+    readonly SPEC_NAME_EMPTY: "Spec name cannot be empty";
+    readonly SPEC_PURPOSE_EMPTY: "Purpose section cannot be empty";
+    readonly SPEC_NO_REQUIREMENTS: "Spec must have at least one requirement";
+    readonly CHANGE_NAME_EMPTY: "Change name cannot be empty";
+    readonly CHANGE_WHY_TOO_SHORT: "Why section must be at least 50 characters";
+    readonly CHANGE_WHY_TOO_LONG: "Why section should not exceed 1000 characters";
+    readonly CHANGE_WHAT_EMPTY: "What Changes section cannot be empty";
+    readonly CHANGE_NO_DELTAS: "Change must have at least one delta";
+    readonly CHANGE_TOO_MANY_DELTAS: "Consider splitting changes with more than 10 deltas";
+    readonly DELTA_SPEC_EMPTY: "Spec name cannot be empty";
+    readonly DELTA_DESCRIPTION_EMPTY: "Delta description cannot be empty";
+    readonly PURPOSE_TOO_BRIEF: "Purpose section is too brief (less than 50 characters)";
+    readonly REQUIREMENT_TOO_LONG: "Requirement text is very long (>500 characters). Consider breaking it down.";
+    readonly DELTA_DESCRIPTION_TOO_BRIEF: "Delta description is too brief";
+    readonly DELTA_MISSING_REQUIREMENTS: "Delta should include requirements";
+    readonly GUIDE_NO_DELTAS: "No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one \"#### Scenario:\" block. Tip: run \"zhuanspec change show <change-id> --json --deltas-only\" to inspect parsed deltas.";
+    readonly GUIDE_MISSING_SPEC_SECTIONS: "Missing required sections. Expected headers: \"## Purpose\" and \"## Requirements\". Example:\n## Purpose\n[brief purpose]\n\n## Requirements\n### Requirement: Clear requirement statement\nUsers SHALL ...\n\n#### Scenario: Descriptive name\n- **WHEN** ...\n- **THEN** ...";
+    readonly GUIDE_MISSING_CHANGE_SECTIONS: "Missing required sections. Expected headers: \"## Why\" and \"## What Changes\". Ensure deltas are documented in specs/ using delta headers.";
+    readonly GUIDE_SCENARIO_FORMAT: "Scenarios must use level-4 headers. Convert bullet lists into:\n#### Scenario: Short name\n- **WHEN** ...\n- **THEN** ...\n- **AND** ...";
+};
+//# sourceMappingURL=constants.d.ts.map

package/dist/core/validation/constants.js

@@ -0,0 +1,40 @@
+/**
+ * Validation threshold constants
+ */
+// Minimum character lengths
+export const MIN_WHY_SECTION_LENGTH = 50;
+export const MIN_PURPOSE_LENGTH = 50;
+// Maximum character/item limits
+export const MAX_WHY_SECTION_LENGTH = 1000;
+export const MAX_REQUIREMENT_TEXT_LENGTH = 500;
+export const MAX_DELTAS_PER_CHANGE = 10;
+// Validation messages
+export const VALIDATION_MESSAGES = {
+    // Required content
+    SCENARIO_EMPTY: 'Scenario text cannot be empty',
+    REQUIREMENT_EMPTY: 'Requirement text cannot be empty',
+    REQUIREMENT_NO_SHALL: 'Requirement must contain SHALL or MUST keyword',
+    REQUIREMENT_NO_SCENARIOS: 'Requirement must have at least one scenario',
+    SPEC_NAME_EMPTY: 'Spec name cannot be empty',
+    SPEC_PURPOSE_EMPTY: 'Purpose section cannot be empty',
+    SPEC_NO_REQUIREMENTS: 'Spec must have at least one requirement',
+    CHANGE_NAME_EMPTY: 'Change name cannot be empty',
+    CHANGE_WHY_TOO_SHORT: `Why section must be at least ${MIN_WHY_SECTION_LENGTH} characters`,
+    CHANGE_WHY_TOO_LONG: `Why section should not exceed ${MAX_WHY_SECTION_LENGTH} characters`,
+    CHANGE_WHAT_EMPTY: 'What Changes section cannot be empty',
+    CHANGE_NO_DELTAS: 'Change must have at least one delta',
+    CHANGE_TOO_MANY_DELTAS: `Consider splitting changes with more than ${MAX_DELTAS_PER_CHANGE} deltas`,
+    DELTA_SPEC_EMPTY: 'Spec name cannot be empty',
+    DELTA_DESCRIPTION_EMPTY: 'Delta description cannot be empty',
+    // Warnings
+    PURPOSE_TOO_BRIEF: `Purpose section is too brief (less than ${MIN_PURPOSE_LENGTH} characters)`,
+    REQUIREMENT_TOO_LONG: `Requirement text is very long (>${MAX_REQUIREMENT_TEXT_LENGTH} characters). Consider breaking it down.`,
+    DELTA_DESCRIPTION_TOO_BRIEF: 'Delta description is too brief',
+    DELTA_MISSING_REQUIREMENTS: 'Delta should include requirements',
+    // Guidance snippets (appended to primary messages for remediation)
+    GUIDE_NO_DELTAS: 'No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one "#### Scenario:" block. Tip: run "zhuanspec change show <change-id> --json --deltas-only" to inspect parsed deltas.',
+    GUIDE_MISSING_SPEC_SECTIONS: 'Missing required sections. Expected headers: "## Purpose" and "## Requirements". Example:\n## Purpose\n[brief purpose]\n\n## Requirements\n### Requirement: Clear requirement statement\nUsers SHALL ...\n\n#### Scenario: Descriptive name\n- **WHEN** ...\n- **THEN** ...',
+    GUIDE_MISSING_CHANGE_SECTIONS: 'Missing required sections. Expected headers: "## Why" and "## What Changes". Ensure deltas are documented in specs/ using delta headers.',
+    GUIDE_SCENARIO_FORMAT: 'Scenarios must use level-4 headers. Convert bullet lists into:\n#### Scenario: Short name\n- **WHEN** ...\n- **THEN** ...\n- **AND** ...',
+};
+//# sourceMappingURL=constants.js.map

package/dist/core/validation/types.d.ts

@@ -0,0 +1,18 @@
+export type ValidationLevel = 'ERROR' | 'WARNING' | 'INFO';
+export interface ValidationIssue {
+    level: ValidationLevel;
+    path: string;
+    message: string;
+    line?: number;
+    column?: number;
+}
+export interface ValidationReport {
+    valid: boolean;
+    issues: ValidationIssue[];
+    summary: {
+        errors: number;
+        warnings: number;
+        info: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/validation/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/validation/validator.d.ts

@@ -0,0 +1,33 @@
+import { ValidationReport } from './types.js';
+export declare class Validator {
+    private strictMode;
+    constructor(strictMode?: boolean);
+    validateSpec(filePath: string): Promise<ValidationReport>;
+    /**
+     * Validate spec content from a string (used for pre-write validation of rebuilt specs)
+     */
+    validateSpecContent(specName: string, content: string): Promise<ValidationReport>;
+    validateChange(filePath: string): Promise<ValidationReport>;
+    /**
+     * Validate delta-formatted spec files under a change directory.
+     * Enforces:
+     * - At least one delta across all files
+     * - ADDED/MODIFIED: each requirement has SHALL/MUST and at least one scenario
+     * - REMOVED: names only; no scenario/description required
+     * - RENAMED: pairs well-formed
+     * - No duplicates within sections; no cross-section conflicts per spec
+     */
+    validateChangeDeltaSpecs(changeDir: string): Promise<ValidationReport>;
+    private convertZodErrors;
+    private applySpecRules;
+    private applyChangeRules;
+    private enrichTopLevelError;
+    private extractNameFromPath;
+    private createReport;
+    isValid(report: ValidationReport): boolean;
+    private extractRequirementText;
+    private containsShallOrMust;
+    private countScenarios;
+    private formatSectionList;
+}
+//# sourceMappingURL=validator.d.ts.map