@bobby_z/openspec 0.0.1

package/schemas/spec-driven/schema.yaml

@@ -0,0 +1,151 @@
+name: spec-driven
+version: 1
+description: 默认 OpenSpec 工作流 - 提案 → 规范 → 设计 → 任务
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: 概述本变更的初始提案文档
+    template: proposal.md
+    instruction: |
+      撰写建立「为何需要本变更」的提案文档。
+
+      章节：
+      - **动机**：用 1～2 句话说明问题或机会。解决什么问题？为什么是现在？
+      - **变更内容**：变更的要点列表。对新能力、修改或移除保持具体。破坏性变更用 **BREAKING** 标出。
+      - **能力**：标明将新增或修改的规范：
+        - **新增能力**：列出将要引入的能力。每项对应新的 `specs/<name>/spec.md`。使用 kebab-case 名称（如 `user-auth`、`data-export`）。
+        - **修改的能力**：其「需求」会发生变化的既有能力。仅当规范级行为变化时列入（而非仅实现细节）。每项需有对应的增量规范文件。在 `openspec/specs/` 中查看已有规范名称。若无需求级变化可留空。
+      - **影响**：受影响的代码、API、依赖或系统。
+
+      重要：能力一节是提案与规范阶段之间的契约，填写前请先查阅现有规范。
+      此处列出的每项能力都需有对应的规范文件。
+
+      保持简洁（1～2 页）。聚焦「为什么」而非「怎么做」——
+      实现细节放在 design.md。
+
+      这是基础——规范、设计和任务都建立在此之上。
+    requires: []
+
+  - id: specs
+    generates: "specs/**/*.md"
+    description: 本变更的详细规范
+    template: spec.md
+    instruction: |
+      创建定义「系统应做什么」的规范文件。
+
+      按提案中「能力」一节列出的每项能力各写一个规范文件。
+      - 新增能力：使用提案中的 kebab-case 名称（specs/<capability>/spec.md）。
+      - 修改的能力：使用 openspec/specs/<capability>/ 下已有规范目录名，在变更目录下创建增量规范 specs/<capability>/spec.md。
+
+      增量操作（使用 ## 标题）：
+      - **ADDED Requirements**：新增能力
+      - **MODIFIED Requirements**：行为变更——必须包含完整更新后的内容
+      - **REMOVED Requirements**：废弃项——必须包含 **Reason** 与 **Migration**
+      - **RENAMED Requirements**：仅名称变更——使用 FROM:/TO: 格式
+
+      需求格式：
+      - 每条需求：`### Requirement: <name>` 后跟描述
+      - 规范性需求使用 SHALL/MUST（避免 should/may）
+      - 每个场景：`#### Scenario: <name>`，采用 WHEN/THEN 格式
+      - **关键**：场景必须使用恰好 4 个井号（`####`）。使用 3 个井号或列表会导致静默失败。
+      - 每条需求至少有一个场景。
+
+      MODIFIED 需求的操作步骤：
+      1. 在 openspec/specs/<capability>/spec.md 中找到现有需求
+      2. 复制整条需求块（从 `### Requirement:` 到其下所有场景）
+      3. 粘贴到 `## MODIFIED Requirements` 下并修改为新行为
+      4. 确保标题文字完全匹配（忽略首尾空白）
+
+      常见错误：MODIFIED 只写部分内容会在归档时丢失细节。
+      若只新增关注点而不改既有行为，请使用 ADDED。
+
+      示例：
+      ```
+      ## ADDED Requirements
+
+      ### Requirement: User can export data
+      The system SHALL allow users to export their data in CSV format.
+
+      #### Scenario: Successful export
+      - **WHEN** user clicks "Export" button
+      - **THEN** system downloads a CSV file with all user data
+
+      ## REMOVED Requirements
+
+      ### Requirement: Legacy export
+      **Reason**: Replaced by new export system
+      **Migration**: Use new export endpoint at /api/v2/export
+      ```
+
+      规范应可检验——每个场景都是潜在测试用例。
+    requires:
+      - proposal
+
+  - id: design
+    generates: design.md
+    description: 含实现细节的技术设计文档
+    template: design.md
+    instruction: |
+      撰写说明「如何实现本变更」的设计文档。
+
+      何时需要 design.md（仅当符合下列任一情况时创建）：
+      - 跨模块变更（多服务/多模块）或新架构模式
+      - 新增外部依赖或显著数据模型变更
+      - 安全、性能或迁移复杂度
+      - 需要在编码前做技术决策以消除歧义
+
+      章节：
+      - **背景**：背景、现状、约束、干系人
+      - **目标 / 非目标**：本设计要达成的结果及明确排除的内容
+      - **决策**：关键技术选择及理由（为何选 X 而非 Y？）。每项决策可简述考虑过的替代方案。
+      - **风险 / 权衡**：已知限制与可能问题。格式：[风险] → 缓解措施
+      - **迁移计划**：部署步骤、回滚策略（若适用）
+      - **待决问题**：尚未确定的决策或未知项
+
+      聚焦架构与方案，而非逐行实现。
+      动机参考提案，需求参考规范。
+
+      好的设计文档会解释技术决策背后的「为什么」。
+    requires:
+      - proposal
+
+  - id: tasks
+    generates: tasks.md
+    description: 可跟踪的实施任务清单
+    template: tasks.md
+    instruction: |
+      创建拆解实施工作的任务列表。
+
+      **重要：请严格按下列模板书写。** 应用阶段会解析勾选格式以跟踪进度，未使用 `- [ ]` 的任务不会被跟踪。
+
+      要点：
+      - 在 ## 编号标题下分组相关任务
+      - 每条任务必须是勾选项：`- [ ] X.Y 任务描述`
+      - 任务粒度以单次会话能完成为宜
+      - 按依赖顺序排列（什么必须先做？）
+
+      示例：
+      ```
+      ## 1. Setup
+
+      - [ ] 1.1 Create new module structure
+      - [ ] 1.2 Add dependencies to package.json
+
+      ## 2. Core Implementation
+
+      - [ ] 2.1 Implement data export function
+      - [ ] 2.2 Add CSV formatting utilities
+      ```
+
+      要做什么参考规范，怎么做参考设计。
+      每条任务应可验证——完成时能明确判断。
+    requires:
+      - specs
+      - design
+
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  instruction: |
+    阅读上下文文件，按顺序处理未完成任务，完成即勾选。
+    若遇阻塞或需要澄清，请先暂停。

package/schemas/spec-driven/templates/design.md

@@ -0,0 +1,21 @@
+## 背景
+
+<!-- 背景与当前状态 -->
+
+## 目标 / 非目标
+
+**目标：**
+
+<!-- 本设计要达成的结果 -->
+
+**非目标：**
+
+<!-- 明确不在范围内的内容 -->
+
+## 决策
+
+<!-- 关键设计决策及理由 -->
+
+## 风险 / 权衡
+
+<!-- 已知风险与权衡 -->

package/schemas/spec-driven/templates/proposal.md

@@ -0,0 +1,25 @@
+## 动机
+
+<!-- 说明本变更的动机。要解决什么问题？为什么是现在？ -->
+
+## 变更内容
+
+<!-- 描述将要发生的变化。对新能力、修改或移除保持具体。 -->
+
+## 能力
+
+### 新增能力
+
+<!-- 将要引入的能力。将 <name> 替换为 kebab-case 标识（如 user-auth、data-export、api-rate-limiting）。每项对应 specs/<name>/spec.md -->
+
+- `<name>`: <该能力涵盖内容的简要说明>
+
+### 修改的能力
+
+<!-- 其「需求」会发生变化的既有能力（而非仅实现层面）。仅在规范级行为变化时列入。每项需有对应的增量规范文件。使用 openspec/specs/ 下已有规范名称。若无需求级变化可留空。 -->
+
+- `<existing-name>`: <正在变更的需求说明>
+
+## 影响
+
+<!-- 受影响的代码、API、依赖或系统 -->

package/schemas/spec-driven/templates/spec.md

@@ -0,0 +1,10 @@
+## ADDED Requirements
+
+### Requirement: <!-- 需求名称 -->
+
+<!-- 需求正文 -->
+
+#### Scenario: <!-- 场景名称 -->
+
+- **WHEN** <!-- 条件 -->
+- **THEN** <!-- 预期结果 -->

package/schemas/spec-driven/templates/tasks.md

@@ -0,0 +1,9 @@
+## 1. <!-- 任务组名称 -->
+
+- [ ] 1.1 <!-- 任务描述 -->
+- [ ] 1.2 <!-- 任务描述 -->
+
+## 2. <!-- 任务组名称 -->
+
+- [ ] 2.1 <!-- 任务描述 -->
+- [ ] 2.2 <!-- 任务描述 -->

package/scripts/postinstall.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall script for auto-installing shell completions
+ *
+ * This script runs automatically after npm install unless:
+ * - CI=true environment variable is set
+ * - OPENSPEC_NO_COMPLETIONS=1 environment variable is set
+ * - dist/ directory doesn't exist (dev setup scenario)
+ *
+ * The script never fails npm install - all errors are caught and handled gracefully.
+ */
+
+import { promises as fs } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Check if we should skip installation
+ */
+function shouldSkipInstallation() {
+  // Skip in CI environments
+  if (process.env.CI === 'true' || process.env.CI === '1') {
+    return { skip: true, reason: 'CI environment detected' };
+  }
+
+  // Skip if user opted out
+  if (process.env.OPENSPEC_NO_COMPLETIONS === '1') {
+    return { skip: true, reason: 'OPENSPEC_NO_COMPLETIONS=1 set' };
+  }
+
+  return { skip: false };
+}
+
+/**
+ * Check if dist/ directory exists
+ */
+async function distExists() {
+  const distPath = path.join(__dirname, '..', 'dist');
+  try {
+    const stat = await fs.stat(distPath);
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect the user's shell
+ */
+async function detectShell() {
+  try {
+    const { detectShell } = await import('../dist/utils/shell-detection.js');
+    const result = detectShell();
+    return result.shell;
+  } catch (error) {
+    // Fail silently if detection module doesn't exist
+    return undefined;
+  }
+}
+
+/**
+ * Install completions for the detected shell
+ */
+async function installCompletions(shell) {
+  try {
+    const { CompletionFactory } = await import('../dist/core/completions/factory.js');
+    const { COMMAND_REGISTRY } = await import('../dist/core/completions/command-registry.js');
+
+    // Check if shell is supported
+    if (!CompletionFactory.isSupported(shell)) {
+      console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+      return;
+    }
+
+    // Generate completion script
+    const generator = CompletionFactory.createGenerator(shell);
+    const script = generator.generate(COMMAND_REGISTRY);
+
+    // Install completion script
+    const installer = CompletionFactory.createInstaller(shell);
+    const result = await installer.install(script);
+
+    if (result.success) {
+      // Show success message based on installation type
+      if (result.isOhMyZsh) {
+        console.log(`✓ Shell completions installed`);
+        console.log(`  Restart shell: exec zsh`);
+      } else if (result.zshrcConfigured) {
+        console.log(`✓ Shell completions installed and configured`);
+        console.log(`  Restart shell: exec zsh`);
+      } else {
+        console.log(`✓ Shell completions installed to ~/.zsh/completions/`);
+        console.log(`  Add to ~/.zshrc: fpath=(~/.zsh/completions $fpath)`);
+        console.log(`  Then: exec zsh`);
+      }
+    } else {
+      // Installation failed, show tip for manual install
+      console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+    }
+  } catch (error) {
+    // Fail gracefully - show tip for manual install
+    console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+  }
+}
+
+/**
+ * Main function
+ */
+async function main() {
+  try {
+    // Check if we should skip
+    const skipCheck = shouldSkipInstallation();
+    if (skipCheck.skip) {
+      // Silent skip - no output
+      return;
+    }
+
+    // Check if dist/ exists (skip silently if not - expected during dev setup)
+    if (!(await distExists())) {
+      return;
+    }
+
+    // Detect shell
+    const shell = await detectShell();
+    if (!shell) {
+      console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+      return;
+    }
+
+    // Install completions
+    await installCompletions(shell);
+  } catch (error) {
+    // Fail gracefully - never break npm install
+    // Show tip for manual install
+    console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+  }
+}
+
+// Run main and handle any unhandled errors
+main().catch(() => {
+  // Silent failure - never break npm install
+  process.exit(0);
+});