@superkou/openspec 1.4.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: |
+      创建提案文档，说明为什么需要这个变更。
+
+      段落：
+      - **Why**：1-2 句话说明问题或机会。解决什么问题？为什么现在做？
+      - **What Changes**：变更列表。具体说明新增、修改或移除的内容。破坏性变更标注 **BREAKING**。
+      - **Capabilities**：标识哪些 spec 将被创建或修改：
+        - **New Capabilities**：新增的能力列表。每个将创建 `specs/<name>/spec.md`。使用 kebab-case 名称（如 `user-auth`、`data-export`）。
+        - **Modified Capabilities**：需求发生改变的既有能力。仅 spec 级别行为变更时填写（不涉及实现细节）。每个需要一份 delta spec 文件。查阅 `openspec/specs/` 下的既有 spec 名称。如无需求变更则留空。
+      - **Impact**：受影响的代码、API、依赖或系统。
+
+      重要：Capabilities 段落是 proposal 与 specs 之间的契约。填写前请先查阅既有 specs。
+      此处列出的每个 capability 后续都需要对应的 spec 文件。
+
+      保持简洁（1-2 页）。关注"为什么做"而不是"怎么做"——实现细节放在 design.md。
+
+      这是基础——specs、design、tasks 都以此为基础构建。
+    requires: []
+
+  - id: specs
+    generates: "specs/**/*.md"
+    description: 详细的变更规格说明
+    template: spec.md
+    instruction: |
+      创建规格文件，定义系统"应该做什么"。
+
+      为 proposal 的 Capabilities 中列出的每个 capability 创建一个 spec 文件。
+      - 新增能力：使用 proposal 中的 kebab-case 名称（specs/<capability>/spec.md）。
+      - 修改能力：使用 openspec/specs/ 中既有的 spec 文件夹名称，在 specs/<capability>/spec.md 创建 delta spec。
+
+      Delta 操作（使用 ## 标题）：
+      - **ADDED Requirements**：新能力
+      - **MODIFIED Requirements**：行为变更 —— 必须包含完整的更新内容
+      - **REMOVED Requirements**：废弃功能 —— 必须包含 **Reason** 和 **Migration**
+      - **RENAMED Requirements**：仅名称变更 —— 使用 FROM:/TO: 格式
+
+      格式要求：
+      - 每个需求：`### Requirement: <名称>` 后跟描述
+      - 使用 SHALL/MUST 或中文的"必须"/"应当"来表述规范性需求
+      - 每个场景：`#### Scenario: <名称>` 使用 WHEN/THEN 格式
+      - **关键**：场景必须使用恰好 4 个 `#`（`####`）。使用 3 个 `#` 或列表格式会静默失败。
+      - 每个需求至少需要一个场景。
+
+      MODIFIED 需求工作流：
+      1. 在 openspec/specs/<capability>/spec.md 中找到既有需求
+      2. 复制整个需求块（从 `### Requirement:` 到所有场景）
+      3. 粘贴到 `## MODIFIED Requirements` 下并编辑为新的行为
+      4. 确保标题文本精确匹配（忽略空白差异）
+
+      常见错误：使用 MODIFIED 但只包含部分内容，归档时信息会丢失。
+      如果不修改既有行为只是新增关注点，请使用 ADDED。
+
+      示例：
+      ```
+      ## ADDED Requirements
+
+      ### Requirement: 用户可导出数据
+      系统 SHALL 允许用户以 CSV 格式导出数据。
+
+      #### Scenario: 成功导出
+      - **WHEN** 用户点击"导出"按钮
+      - **THEN** 系统下载包含所有用户数据的 CSV 文件
+
+      ## REMOVED Requirements
+
+      ### Requirement: 旧版导出
+      **Reason**: 已被新版导出系统替代
+      **Migration**: 使用 /api/v2/export 新端点
+      ```
+
+      Specs 应该可测试——每个场景都是一个潜在的测试用例。
+    requires:
+      - proposal
+
+  - id: design
+    generates: design.md
+    description: 包含实现细节的技术设计文档
+    template: design.md
+    instruction: |
+      创建设计文档，说明如何实现变更。
+
+      何时需要 design.md（满足任一即创建）：
+      - 跨层变更（多个服务/模块）或新架构模式
+      - 新增外部依赖或重大数据模型变更
+      - 涉及安全、性能或迁移复杂度
+      - 编码前需要先做技术决策来消除不确定性
+
+      段落：
+      - **Context**：背景、当前状态、约束条件、相关方
+      - **Goals / Non-Goals**：本设计的目标和明确排除的内容
+      - **Decisions**：关键技术选择及理由（为什么选 X 而非 Y？）。为每个决策包含被否决的备选方案。
+      - **Risks / Trade-offs**：已知限制和可能出错的地方。格式：[风险] → 缓解措施
+      - **Migration Plan**：部署步骤、回滚策略（如适用）
+      - **Open Questions**：待解决的决策或未知信息
+
+      聚焦于架构和方法，而非逐行实现细节。
+      引用 proposal 了解动机，引用 specs 了解需求。
+
+      好的设计文档阐述技术决策背后的"为什么"。
+    requires:
+      - proposal
+
+  - id: tasks
+    generates: tasks.md
+    description: 带勾选框的可执行任务清单
+    template: tasks.md
+    instruction: |
+      创建任务清单，将实现工作拆解为可执行的步骤。
+
+      **重要：严格遵循下方模板。** apply 阶段解析复选框格式来追踪进度。
+      未使用 `- [ ]` 格式的任务不会被追踪。
+
+      指引：
+      - 用 ## 编号标题分组相关任务
+      - 每个任务必须是复选框：`- [ ] X.Y 任务描述`
+      - 任务应足够小，一次工作会话内可完成
+      - 按依赖顺序排列任务（什么先做？）
+
+      示例：
+      ```
+      ## 1. 准备
+
+      - [ ] 1.1 创建新模块结构
+      - [ ] 1.2 添加依赖到 package.json
+
+      ## 2. 核心实现
+
+      - [ ] 2.1 实现数据导出函数
+      - [ ] 2.2 添加 CSV 格式化工具
+      ```
+
+      参考 specs 了解需要构建什么，参考 design 了解如何构建。
+      每个任务应可验证——完成即知。
+    requires:
+      - specs
+      - design
+
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  instruction: |
+    阅读上下文文件，逐个完成待处理任务，完成后标记为已完成。
+    遇到阻塞或需要澄清时暂停。

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

@@ -0,0 +1,19 @@
+## Context
+
+<!-- 背景和当前状态 -->
+
+## Goals / Non-Goals
+
+**Goals:**
+<!-- 本设计的目标 -->
+
+**Non-Goals:**
+<!-- 明确排除在范围之外的内容 -->
+
+## Decisions
+
+<!-- 关键设计决策及其理由 -->
+
+## Risks / Trade-offs
+
+<!-- 已知风险和取舍 -->

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

@@ -0,0 +1,23 @@
+## Why
+
+<!-- 说明此变更的动机。解决什么问题？为什么现在做？ -->
+
+## What Changes
+
+<!-- 描述将要发生的变化。具体说明新增、修改或移除了什么。 -->
+
+## Capabilities
+
+### New Capabilities
+<!-- 引入的新能力。将 <name> 替换为 kebab-case 标识符（例如 user-auth、data-export、api-rate-limiting）。每个将创建 specs/<name>/spec.md -->
+- `<name>`: <此能力覆盖范围的简要描述>
+
+### Modified Capabilities
+<!-- 需求发生变化的既有能力（不涉及实现细节）。
+     仅当 spec 级别行为变化时列出。每个需要 delta spec 文件。
+     使用 openspec/specs/ 中的既有 spec 名称。如无需求变更则留空。 -->
+- `<existing-name>`: <哪些需求正在变化>
+
+## Impact
+
+<!-- 受影响的代码、API、依赖、系统 -->

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

@@ -0,0 +1,8 @@
+## 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/schemas/workspace-planning/schema.yaml

@@ -0,0 +1,72 @@
+name: workspace-planning
+version: 1
+description: Workspace planning workflow for cross-area changes
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Shared workspace proposal with the product goal, scope, affected areas, and impact
+    template: proposal.md
+    instruction: |
+      Create the workspace-level proposal that captures the shared product goal once.
+
+      Sections:
+      - **Why**: Explain the product goal or problem in 1-2 concise paragraphs.
+      - **What Changes**: List the cross-area behavior, workflow, or capability changes.
+      - **Affected Areas**: Name known affected areas using registered workspace link names where applicable. If scope is still being explored, say what remains unresolved.
+      - **Capabilities**: Identify workspace-scoped capabilities that need specs. Area-specific requirements should later live under `specs/<area-or-repo>/<capability>/spec.md`.
+      - **Impact**: Summarize user-facing impact, planning impact, and likely implementation homes without creating repo-local artifacts.
+
+      Keep linked repos and folders as exploration context until an explicit implementation workflow selects an affected area.
+    requires: []
+
+  - id: specs
+    generates: "specs/**/*.md"
+    description: Workspace-scoped specs organized by affected area and capability
+    template: spec.md
+    instruction: |
+      Create workspace-scoped specification files that define WHAT should change.
+
+      Use `specs/<area-or-repo>/<capability>/spec.md` for area-specific requirements. The first path segment should be a registered workspace link name when a registered area owns the requirement. If the area is unresolved, use an exploratory area name and make the unresolved question explicit in the requirement or scenario.
+
+      These specs are planning artifacts under the workspace change root. Do not create repo-local spec files in linked repos during workspace planning.
+
+      Delta operations (use ## headers):
+      - **ADDED Requirements**: New workspace-scoped behavior.
+      - **MODIFIED Requirements**: Changed behavior; include the full updated requirement.
+      - **REMOVED Requirements**: Deprecated behavior with Reason and Migration.
+      - **RENAMED Requirements**: Name changes only; use FROM:/TO: format.
+
+      Each requirement must use SHALL/MUST language and include at least one `#### Scenario:` block.
+    requires:
+      - proposal
+
+  - id: design
+    generates: design.md
+    description: Cross-area technical design and coordination decisions
+    template: design.md
+    instruction: |
+      Create the cross-area design document for workspace planning.
+
+      Focus on decisions that affect multiple areas, handoffs between areas, shared constraints, sequencing risks, and how the workspace plan should stay the source of truth. Avoid line-by-line implementation details and do not instruct agents to edit linked repos until an explicit implementation workflow provides an allowed edit root.
+    requires:
+      - proposal
+
+  - id: tasks
+    generates: tasks.md
+    description: Coordination checklist for workspace planning and later affected-area implementation
+    template: tasks.md
+    instruction: |
+      Create the workspace coordination task list.
+
+      Group tasks by phase or affected area as useful. Each actionable item must be a checkbox using `- [ ]`. When implementation tasks are area-specific, name the affected area and keep the task at planning granularity until a later implementation workflow selects an allowed edit root.
+    requires:
+      - specs
+      - design
+
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  instruction: |
+    Read the workspace planning context from status and instructions output before applying.
+    Select an affected area and confirm an allowed edit root before making implementation edits.
+    Until an explicit implementation context is available, treat linked repos and folders as read-only exploration context.

package/schemas/workspace-planning/templates/design.md

@@ -0,0 +1,33 @@
+## Context
+
+Summarize the workspace planning context, relevant linked areas, and constraints.
+
+## Goals / Non-Goals
+
+**Goals:**
+-
+
+**Non-Goals:**
+- Creating repo-local implementation artifacts before an affected area is selected.
+
+## Decisions
+
+### Decision: <title>
+
+<decision and rationale>
+
+Alternative considered: <alternative and why it was not chosen>
+
+## Risks / Trade-offs
+
+- <risk> -> <mitigation>
+
+## Coordination Notes
+
+- Affected areas:
+- Open handoffs:
+- Implementation entry criteria:
+
+## Open Questions
+
+-

package/schemas/workspace-planning/templates/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+Describe the shared product goal, problem, or opportunity that makes this workspace-level change worth planning.
+
+## What Changes
+
+-
+
+## Affected Areas
+
+- Known:
+- Unresolved:
+
+## Capabilities
+
+### New Capabilities
+
+-
+
+### Modified Capabilities
+
+-
+
+## Impact
+
+- Workspace planning:
+- Linked repos or folders:
+- User-facing behavior:

package/schemas/workspace-planning/templates/spec.md

@@ -0,0 +1,9 @@
+## ADDED Requirements
+
+### Requirement: <workspace requirement name>
+The workspace plan SHALL describe the required behavior and affected area without creating repo-local artifacts during planning.
+
+#### Scenario: <scenario name>
+- **GIVEN** <context>
+- **WHEN** <action>
+- **THEN** <observable result>

package/schemas/workspace-planning/templates/tasks.md

@@ -0,0 +1,15 @@
+## 1. Workspace Planning
+
+- [ ] 1.1 Confirm the shared product goal and unresolved scope questions.
+- [ ] 1.2 Identify affected areas using registered workspace link names where applicable.
+- [ ] 1.3 Review workspace-scoped specs and design before selecting implementation areas.
+
+## 2. Affected Area Implementation
+
+- [ ] 2.1 Select an affected area and confirm its allowed edit root before implementation.
+- [ ] 2.2 Create or update repo-local implementation artifacts only after the area is selected.
+
+## 3. Verification
+
+- [ ] 3.1 Verify workspace planning artifacts remain the source of truth.
+- [ ] 3.2 Record manual acceptance evidence and follow-up fixes.

package/scripts/postinstall.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall script that hints about shell completions
+ *
+ * Completion installation is opt-in: the user must run
+ * `openspec completion install` explicitly. This script only
+ * prints a one-line tip after npm install.
+ *
+ * The tip is suppressed when:
+ * - 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;
+  }
+}
+
+/**
+ * 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;
+    }
+
+    // Completions are opt-in — just print a hint
+    console.log(`\nTip: Run 'openspec completion install' for shell completions`);
+  } catch (error) {
+    // Fail gracefully - never break npm install
+  }
+}
+
+// Run main and handle any unhandled errors
+main().catch(() => {
+  // Silent failure - never break npm install
+  process.exit(0);
+});