calc-mcp-server 0.1.0

package/.claude/skills/openspec-ff-change/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: openspec-ff-change
+description: 快速创建 OpenSpec 产物。当用户想要快速创建实施所需的所有产物而不必单独逐步完成时使用。
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+快速创建产物 - 一次性生成开始实施所需的一切。
+
+**输入**：用户的请求应包含变更名称（kebab-case）或他们想要构建的内容的描述。
+
+**步骤**
+
+1. **如果没有提供明确的输入，询问他们想要构建什么**
+
+   使用 **AskUserQuestion 工具**（开放式，无预设选项）询问：
+   > "你想进行什么变更？描述你想构建或修复的内容。"
+
+   从他们的描述中，得出一个 kebab-case 名称（例如，"增加用户认证" → `add-user-auth`）。
+
+   **重要**：在不了解用户想要构建什么之前，不要继续。
+
+2. **创建变更目录**
+   ```bash
+   openspec new change "<name>"
+   ```
+   这将在 `openspec/changes/<name>/` 下创建一个脚手架变更。
+
+3. **获取产物构建顺序**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   解析 JSON 以获取：
+   - `applyRequires`：实施前所需的产物 ID 数组（例如，`["tasks"]`）
+   - `artifacts`：所有产物及其状态和依赖关系的列表
+
+4. **按顺序创建产物直到准备好实施**
+
+   使用 **TodoWrite 工具** 跟踪产物的进度。
+
+   按依赖顺序循环产物（没有待处理依赖的产物优先）：
+
+   a. **对于每个 `ready`（依赖已满足）的产物**：
+      - 获取指令：
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - 指令 JSON 包括：
+        - `context`：项目背景（给你的约束 - 不要包含在输出中）
+        - `rules`：产物特定规则（给你的约束 - 不要包含在输出中）
+        - `template`：用于输出文件的结构
+        - `instruction`：此产物类型的 Schema 特定指导
+        - `outputPath`：写入产物的位置
+        - `dependencies`：已完成的产物，用于阅读上下文
+      - 阅读任何已完成的依赖文件以获取上下文
+      - 使用 `template` 作为结构创建产物文件
+      - 应用 `context` 和 `rules` 作为约束 - 但不要将它们复制到文件中
+      - 显示简要进度："✓ Created <artifact-id>"
+
+   b. **继续直到所有 `applyRequires` 产物都完成**
+      - 创建每个产物后，重新运行 `openspec status --change "<name>" --json`
+      - 检查 `applyRequires` 中的每个产物 ID 是否在产物数组中具有 `status: "done"`
+      - 当所有 `applyRequires` 产物都完成时停止
+
+   c. **如果产物需要用户输入**（上下文不清楚）：
+      - 使用 **AskUserQuestion 工具** 澄清
+      - 然后继续创建
+
+5. **显示最终状态**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**输出**
+
+完成所有产物后，总结：
+- 变更名称和位置
+- 已创建产物的列表及简要描述
+- 准备就绪："所有产物已创建！准备实施。"
+- 提示："运行 `/opsx:apply` 或让我实施以开始处理任务。"
+
+**产物创建指南**
+
+- 遵循每个产物类型的 `openspec instructions` 中的 `instruction` 字段
+- Schema 定义了每个产物应包含的内容 - 遵循它
+- 在创建新产物之前阅读依赖产物以获取上下文
+- 使用 `template` 作为起点，根据上下文填充
+- **重要**：`context` 和 `rules` 是给你的约束，不是文件内容
+  - 不要将 `<context>`, `<rules>`, `<project_context>` 块复制到产物中
+  - 这些指导你写什么，但绝不应出现在输出中
+
+**护栏**
+- 创建实施所需的所有产物（由 Schema 的 `apply.requires` 定义）
+- 在创建新产物之前始终阅读依赖产物
+- 如果上下文严重不清楚，询问用户 - 但倾向于做出合理的决定以保持势头
+- 如果具有该名称的变更已存在，询问用户是否要继续该变更或创建一个新的
+- 在继续下一个之前，验证每个产物文件在写入后是否存在

package/.claude/skills/openspec-new-change/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: openspec-new-change
+description: 使用实验性产物工作流开始一个新的 OpenSpec 变更。当用户想要以结构化的分步方法创建新功能、修复或修改时使用。
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+使用实验性产物驱动方法开始一个新的变更。
+
+**输入**：用户的请求应包含变更名称（kebab-case）或他们想要构建的内容的描述。
+
+**步骤**
+
+1. **如果没有提供明确的输入，询问他们想要构建什么**
+
+   使用 **AskUserQuestion 工具**（开放式，无预设选项）询问：
+   > "你想进行什么变更？描述你想构建或修复的内容。"
+
+   从他们的描述中，得出一个 kebab-case 名称（例如，"增加用户认证" → `add-user-auth`）。
+
+   **重要**：在不了解用户想要构建什么之前，不要继续。
+
+2. **确定工作流 Schema**
+
+   使用默认 Schema（省略 `--schema`），除非用户明确请求不同的工作流。
+
+   **仅在用户提及时使用不同的 Schema：**
+   - 特定的 Schema 名称 → 使用 `--schema <name>`
+   - "显示工作流" 或 "什么工作流" → 运行 `openspec schemas --json` 并让他们选择
+
+   **否则**：省略 `--schema` 以使用默认值。
+
+3. **创建变更目录**
+   ```bash
+   openspec new change "<name>"
+   ```
+   仅在用户请求特定工作流时添加 `--schema <name>`。
+   这将在 `openspec/changes/<name>/` 下创建一个使用所选 Schema 的脚手架变更。
+
+4. **显示产物状态**
+   ```bash
+   openspec status --change "<name>"
+   ```
+   这显示了哪些产物需要创建，哪些已就绪（依赖关系已满足）。
+
+5. **获取第一个产物的指令**
+   第一个产物取决于 Schema（例如，spec-driven 的 `proposal`）。
+   检查状态输出，找到第一个状态为 "ready" 的产物。
+   ```bash
+   openspec instructions <first-artifact-id> --change "<name>"
+   ```
+   这输出创建第一个产物的模板和上下文。
+
+6. **停止并等待用户指示**
+
+**输出**
+
+完成步骤后，总结：
+- 变更名称和位置
+- 正在使用的 Schema/工作流及其产物序列
+- 当前状态（0/N 产物完成）
+- 第一个产物的模板
+- 提示："准备好创建第一个产物了吗？只需描述这个变更的内容，我会起草它，或者你可以让我继续。"
+
+**护栏**
+- 不要创建任何产物 - 仅显示指令
+- 不要超越显示第一个产物模板
+- 如果名称无效（不是 kebab-case），要求一个有效名称
+- 如果具有该名称的变更已存在，建议继续该变更
+- 如果使用非默认工作流，传递 --schema

package/.claude/skills/openspec-onboard/SKILL.md

@@ -0,0 +1,538 @@
+---
+name: openspec-onboard
+description: Guided onboarding for OpenSpec - walk through a complete workflow cycle with narration and real codebase work.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.1.1"
+---
+
+Guide the user through their first complete OpenSpec workflow cycle. This is a teaching experience—you'll do real work in their codebase while explaining each step.
+
+---
+
+## Preflight
+
+Before starting, check if the OpenSpec CLI is installed:
+
+```bash
+# Unix/macOS
+openspec --version 2>&1 || echo "CLI_NOT_INSTALLED"
+# Windows (PowerShell)
+# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo "CLI_NOT_INSTALLED" }
+```
+
+**If CLI not installed:**
+> OpenSpec CLI is not installed. Install it first, then come back to `/opsx:onboard`.
+
+Stop here if not installed.
+
+---
+
+## Phase 1: Welcome
+
+Display:
+
+```
+## Welcome to OpenSpec!
+
+I'll walk you through a complete change cycle—from idea to implementation—using a real task in your codebase. Along the way, you'll learn the workflow by doing it.
+
+**What we'll do:**
+1. Pick a small, real task in your codebase
+2. Explore the problem briefly
+3. Create a change (the container for our work)
+4. Build the artifacts: proposal → specs → design → tasks
+5. Implement the tasks
+6. Archive the completed change
+
+**Time:** ~15-20 minutes
+
+Let's start by finding something to work on.
+```
+
+---
+
+## Phase 2: Task Selection
+
+### Codebase Analysis
+
+Scan the codebase for small improvement opportunities. Look for:
+
+1. **TODO/FIXME comments** - Search for `TODO`, `FIXME`, `HACK`, `XXX` in code files
+2. **Missing error handling** - `catch` blocks that swallow errors, risky operations without try-catch
+3. **Functions without tests** - Cross-reference `src/` with test directories
+4. **Type issues** - `any` types in TypeScript files (`: any`, `as any`)
+5. **Debug artifacts** - `console.log`, `console.debug`, `debugger` statements in non-debug code
+6. **Missing validation** - User input handlers without validation
+
+Also check recent git activity:
+```bash
+# Unix/macOS
+git log --oneline -10 2>/dev/null || echo "No git history"
+# Windows (PowerShell)
+# git log --oneline -10 2>$null; if ($LASTEXITCODE -ne 0) { echo "No git history" }
+```
+
+### Present Suggestions
+
+From your analysis, present 3-4 specific suggestions:
+
+```
+## Task Suggestions
+
+Based on scanning your codebase, here are some good starter tasks:
+
+**1. [Most promising task]**
+   Location: `src/path/to/file.ts:42`
+   Scope: ~1-2 files, ~20-30 lines
+   Why it's good: [brief reason]
+
+**2. [Second task]**
+   Location: `src/another/file.ts`
+   Scope: ~1 file, ~15 lines
+   Why it's good: [brief reason]
+
+**3. [Third task]**
+   Location: [location]
+   Scope: [estimate]
+   Why it's good: [brief reason]
+
+**4. Something else?**
+   Tell me what you'd like to work on.
+
+Which task interests you? (Pick a number or describe your own)
+```
+
+**If nothing found:** Fall back to asking what the user wants to build:
+> I didn't find obvious quick wins in your codebase. What's something small you've been meaning to add or fix?
+
+### Scope Guardrail
+
+If the user picks or describes something too large (major feature, multi-day work):
+
+```
+That's a valuable task, but it's probably larger than ideal for your first OpenSpec run-through.
+
+For learning the workflow, smaller is better—it lets you see the full cycle without getting stuck in implementation details.
+
+**Options:**
+1. **Slice it smaller** - What's the smallest useful piece of [their task]? Maybe just [specific slice]?
+2. **Pick something else** - One of the other suggestions, or a different small task?
+3. **Do it anyway** - If you really want to tackle this, we can. Just know it'll take longer.
+
+What would you prefer?
+```
+
+Let the user override if they insist—this is a soft guardrail.
+
+---
+
+## Phase 3: Explore Demo
+
+Once a task is selected, briefly demonstrate explore mode:
+
+```
+Before we create a change, let me quickly show you **explore mode**—it's how you think through problems before committing to a direction.
+```
+
+Spend 1-2 minutes investigating the relevant code:
+- Read the file(s) involved
+- Draw a quick ASCII diagram if it helps
+- Note any considerations
+
+```
+## Quick Exploration
+
+[Your brief analysis—what you found, any considerations]
+
+┌─────────────────────────────────────────┐
+│   [Optional: ASCII diagram if helpful]  │
+└─────────────────────────────────────────┘
+
+Explore mode (`/opsx:explore`) is for this kind of thinking—investigating before implementing. You can use it anytime you need to think through a problem.
+
+Now let's create a change to hold our work.
+```
+
+**PAUSE** - Wait for user acknowledgment before proceeding.
+
+---
+
+## Phase 4: Create the Change
+
+**EXPLAIN:**
+```
+## Creating a Change
+
+A "change" in OpenSpec is a container for all the thinking and planning around a piece of work. It lives in `openspec/changes/<name>/` and holds your artifacts—proposal, specs, design, tasks.
+
+Let me create one for our task.
+```
+
+**DO:** Create the change with a derived kebab-case name:
+```bash
+openspec new change "<derived-name>"
+```
+
+**SHOW:**
+```
+Created: `openspec/changes/<name>/`
+
+The folder structure:
+```
+openspec/changes/<name>/
+├── proposal.md    ← Why we're doing this (empty, we'll fill it)
+├── design.md      ← How we'll build it (empty)
+├── specs/         ← Detailed requirements (empty)
+└── tasks.md       ← Implementation checklist (empty)
+```
+
+Now let's fill in the first artifact—the proposal.
+```
+
+---
+
+## Phase 5: Proposal
+
+**EXPLAIN:**
+```
+## The Proposal
+
+The proposal captures **why** we're making this change and **what** it involves at a high level. It's the "elevator pitch" for the work.
+
+I'll draft one based on our task.
+```
+
+**DO:** Draft the proposal content (don't save yet):
+
+```
+Here's a draft proposal:
+
+---
+
+## Why
+
+[1-2 sentences explaining the problem/opportunity]
+
+## What Changes
+
+[Bullet points of what will be different]
+
+## Capabilities
+
+### New Capabilities
+- `<capability-name>`: [brief description]
+
+### Modified Capabilities
+<!-- If modifying existing behavior -->
+
+## Impact
+
+- `src/path/to/file.ts`: [what changes]
+- [other files if applicable]
+
+---
+
+Does this capture the intent? I can adjust before we save it.
+```
+
+**PAUSE** - Wait for user approval/feedback.
+
+After approval, save the proposal:
+```bash
+openspec instructions proposal --change "<name>" --json
+```
+Then write the content to `openspec/changes/<name>/proposal.md`.
+
+```
+Proposal saved. This is your "why" document—you can always come back and refine it as understanding evolves.
+
+Next up: specs.
+```
+
+---
+
+## Phase 6: Specs
+
+**EXPLAIN:**
+```
+## Specs
+
+Specs define **what** we're building in precise, testable terms. They use a requirement/scenario format that makes expected behavior crystal clear.
+
+For a small task like this, we might only need one spec file.
+```
+
+**DO:** Create the spec file:
+```bash
+# Unix/macOS
+mkdir -p openspec/changes/<name>/specs/<capability-name>
+# Windows (PowerShell)
+# New-Item -ItemType Directory -Force -Path "openspec/changes/<name>/specs/<capability-name>"
+```
+
+Draft the spec content:
+
+```
+Here's the spec:
+
+---
+
+## ADDED Requirements
+
+### Requirement: <Name>
+
+<Description of what the system should do>
+
+#### Scenario: <Scenario name>
+
+- **WHEN** <trigger condition>
+- **THEN** <expected outcome>
+- **AND** <additional outcome if needed>
+
+---
+
+This format—WHEN/THEN/AND—makes requirements testable. You can literally read them as test cases.
+```
+
+Save to `openspec/changes/<name>/specs/<capability>/spec.md`.
+
+---
+
+## Phase 7: Design
+
+**EXPLAIN:**
+```
+## Design
+
+The design captures **how** we'll build it—technical decisions, tradeoffs, approach.
+
+For small changes, this might be brief. That's fine—not every change needs deep design discussion.
+```
+
+**DO:** Draft design.md:
+
+```
+Here's the design:
+
+---
+
+## Context
+
+[Brief context about the current state]
+
+## Goals / Non-Goals
+
+**Goals:**
+- [What we're trying to achieve]
+
+**Non-Goals:**
+- [What's explicitly out of scope]
+
+## Decisions
+
+### Decision 1: [Key decision]
+
+[Explanation of approach and rationale]
+
+---
+
+For a small task, this captures the key decisions without over-engineering.
+```
+
+Save to `openspec/changes/<name>/design.md`.
+
+---
+
+## Phase 8: Tasks
+
+**EXPLAIN:**
+```
+## Tasks
+
+Finally, we break the work into implementation tasks—checkboxes that drive the apply phase.
+
+These should be small, clear, and in logical order.
+```
+
+**DO:** Generate tasks based on specs and design:
+
+```
+Here are the implementation tasks:
+
+---
+
+## 1. [Category or file]
+
+- [ ] 1.1 [Specific task]
+- [ ] 1.2 [Specific task]
+
+## 2. Verify
+
+- [ ] 2.1 [Verification step]
+
+---
+
+Each checkbox becomes a unit of work in the apply phase. Ready to implement?
+```
+
+**PAUSE** - Wait for user to confirm they're ready to implement.
+
+Save to `openspec/changes/<name>/tasks.md`.
+
+---
+
+## Phase 9: Apply (Implementation)
+
+**EXPLAIN:**
+```
+## Implementation
+
+Now we implement each task, checking them off as we go. I'll announce each one and occasionally note how the specs/design informed the approach.
+```
+
+**DO:** For each task:
+
+1. Announce: "Working on task N: [description]"
+2. Implement the change in the codebase
+3. Reference specs/design naturally: "The spec says X, so I'm doing Y"
+4. Mark complete in tasks.md: `- [ ]` → `- [x]`
+5. Brief status: "✓ Task N complete"
+
+Keep narration light—don't over-explain every line of code.
+
+After all tasks:
+
+```
+## Implementation Complete
+
+All tasks done:
+- [x] Task 1
+- [x] Task 2
+- [x] ...
+
+The change is implemented! One more step—let's archive it.
+```
+
+---
+
+## Phase 10: Archive
+
+**EXPLAIN:**
+```
+## Archiving
+
+When a change is complete, we archive it. This moves it from `openspec/changes/` to `openspec/changes/archive/YYYY-MM-DD-<name>/`.
+
+Archived changes become your project's decision history—you can always find them later to understand why something was built a certain way.
+```
+
+**DO:**
+```bash
+openspec archive "<name>"
+```
+
+**SHOW:**
+```
+Archived to: `openspec/changes/archive/YYYY-MM-DD-<name>/`
+
+The change is now part of your project's history. The code is in your codebase, the decision record is preserved.
+```
+
+---
+
+## Phase 11: Recap & Next Steps
+
+```
+## Congratulations!
+
+You just completed a full OpenSpec cycle:
+
+1. **Explore** - Thought through the problem
+2. **New** - Created a change container
+3. **Proposal** - Captured WHY
+4. **Specs** - Defined WHAT in detail
+5. **Design** - Decided HOW
+6. **Tasks** - Broke it into steps
+7. **Apply** - Implemented the work
+8. **Archive** - Preserved the record
+
+This same rhythm works for any size change—a small fix or a major feature.
+
+---
+
+## Command Reference
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:explore` | Think through problems before/during work |
+| `/opsx:new` | Start a new change, step through artifacts |
+| `/opsx:ff` | Fast-forward: create all artifacts at once |
+| `/opsx:continue` | Continue working on an existing change |
+| `/opsx:apply` | Implement tasks from a change |
+| `/opsx:verify` | Verify implementation matches artifacts |
+| `/opsx:archive` | Archive a completed change |
+
+---
+
+## What's Next?
+
+Try `/opsx:new` or `/opsx:ff` on something you actually want to build. You've got the rhythm now!
+```
+
+---
+
+## Graceful Exit Handling
+
+### User wants to stop mid-way
+
+If the user says they need to stop, want to pause, or seem disengaged:
+
+```
+No problem! Your change is saved at `openspec/changes/<name>/`.
+
+To pick up where we left off later:
+- `/opsx:continue <name>` - Resume artifact creation
+- `/opsx:apply <name>` - Jump to implementation (if tasks exist)
+
+The work won't be lost. Come back whenever you're ready.
+```
+
+Exit gracefully without pressure.
+
+### User just wants command reference
+
+If the user says they just want to see the commands or skip the tutorial:
+
+```
+## OpenSpec Quick Reference
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:explore` | Think through problems (no code changes) |
+| `/opsx:new <name>` | Start a new change, step by step |
+| `/opsx:ff <name>` | Fast-forward: all artifacts at once |
+| `/opsx:continue <name>` | Continue an existing change |
+| `/opsx:apply <name>` | Implement tasks |
+| `/opsx:verify <name>` | Verify implementation |
+| `/opsx:archive <name>` | Archive when done |
+
+Try `/opsx:new` to start your first change, or `/opsx:ff` if you want to move fast.
+```
+
+Exit gracefully.
+
+---
+
+## Guardrails
+
+- **Follow the EXPLAIN → DO → SHOW → PAUSE pattern** at key transitions (after explore, after proposal draft, after tasks, after archive)
+- **Keep narration light** during implementation—teach without lecturing
+- **Don't skip phases** even if the change is small—the goal is teaching the workflow
+- **Pause for acknowledgment** at marked points, but don't over-pause
+- **Handle exits gracefully**—never pressure the user to continue
+- **Use real codebase tasks**—don't simulate or use fake examples
+- **Adjust scope gently**—guide toward smaller tasks but respect user choice