Commit Message & Release Note 规范

本 Skill 定义了 Sharp GUI 项目的 Git Commit Message 和 GitHub Release Note 的书写格式规范。当用户要求生成 commit message 或 release note 时，必须严格遵循以下规则。

Commit Message 规范

格式

使用 Conventional Commits 格式，语言为 中文。

生成 commit message 前，先执行 git diff --staged --stat（必要时再看 git diff --staged）核对真实改动范围，确保 type / scope 与描述和实际改动一致，避免"描述与改动不符"。

标题行

type(scope): 简要描述

• type: feat | fix | refactor | chore | docs | style | perf | revert
  • feat 新功能、fix 修复、refactor 重构、perf 性能、style 纯样式/格式、docs 文档、chore 杂项/构建/依赖、revert 回滚
  • 例外：merge 提交、Initial commit、自动生成的提交不强制套用本格式
• scope (可选): 影响的模块，建议从以下约定值中选取，确需新增时保持一致：
  • 功能域：photo | video | viewer | frontend | app | backend | share | vr
  • 工程域：install | update | run | release | build | openspec
  • 文档可用复合形式：docs(openspec) | docs(frontend) | docs(video)
• 标题行 不超过 72 字符，只写"做了什么"；细节一律进正文，不要用 - 把多条变更塞进标题
• 不以句号结尾

原子提交 (优先)

• 优先一个提交只做一件事：type 单一、范围聚焦，方便 review 与回滚
• 确有多项改动必须合并时：标题取主导改动对应的 type，其余变更在正文按分类说明（见下方"大改动"示例）；不要在标题用 & 堆叠多个 type

破坏性变更 / 关联 Issue

• 破坏性变更：在 type 后加 !（如 feat(app)!: ...），并在正文末尾追加一行 BREAKING CHANGE: 说明
• 关联 issue / PR：在正文末尾追加 Closes #123 或 Refs #123

前端构建产物 (涉及前端改动时必须)

• 只要改动涉及 frontend/，提交前必须先执行 npm run build 重新生成 dist/，并将更新后的 dist/ 一并纳入提交，确保发布版本无需用户自行构建即可使用最新前端
• 纯后端 / 文档 / 脚本改动无需重建 dist/，避免产生无意义的大 diff
• 若仅同步构建产物，可单独用 chore(build): 同步前端构建产物 提交，避免淹没功能 diff

版本号变更

• 版本号以 version.txt 为准；发布时使用独立提交 chore(release): 发布 vX.Y.Z（同步 version.txt），便于检索版本节点
• 不要把版本号 bump 混进功能提交里

正文 (大改动才需要)

• 用空行与标题分隔
• 按分类组织，分类名后接冒号
• 用 - 列表描述具体变更
• 二级细节用缩进 -
• 简洁，不写废话
• 语言统一 中文；历史遗留的英文提交不强制回改

示例

小改动 (单行即可):

fix: 赋予 update.sh 执行权限

中等改动 (附简短说明):

fix: update.py 解压路径修复 - 移至 tools/ 后解压到了错误目录

get_script_dir() 返回 tools/ 而非项目根目录，导致 zip 被解压
到 tools/ 内而不是项目根目录。改为返回 tools/ 的父目录。

大改动 (分类组织):

feat: 添加自动更新脚本 & 重构工具目录 & 修复 install.bat 闪退

新增功能:
- 添加 update.py/update.bat/update.sh 自动更新脚本
  - GitHub Release 版本检测 (无 API 限流)
  - 版本比较防止降级 (pre-release → 旧 stable)
- release.yml 自动写入 version.txt

目录重构:
- 工具脚本移至 tools/ 目录
  - detect_cuda.py, download_model.py, generate_cert.py, update.py
- 更新所有引用: install.bat/sh, release.yml, README.md 等

Bug 修复 (install.bat):
- 修复 CUDA 检测闪退: for /f 内联 Python 语法冲突
- 修复 nvcc 版本解析带尾部逗号 (12.4, → 12.4)

Release Note 规范

定位

• 面向普通用户，不展示过多技术实现细节
• 中英双语，每行先中文后英文，用 / 分隔
• 语气简洁明了，突出用户能感知到的变化和价值
• 输出时使用 markdown 代码块包裹，方便用户直接复制

结构模板

## 🚀 vX.Y.Z(-rc.N) (Pre-Release)

> ⚠️ 这是预发布版本，用于测试验证。正式版将在测试通过后发布。
>
> ⚠️ This is a pre-release for testing. Stable release coming after validation.

---

### 🎯 功能标题 / Feature Title

- **中文粗体关键词**: 中文描述 / English description
- **中文粗体关键词**: 中文描述 / English description

### 🐛 Bug 修复 / Bug Fixes

- **修复 xxx**: 中文描述 / English description

### 🔧 技术改进 / Technical Improvements

- 中文描述 / English description

---

### 📦 快速使用 / Quick Start

1. 下载 `sharp-gui-vX.Y.Z.zip` / Download the zip file
2. 解压后运行安装脚本 / Extract and run install script:
   - **Linux/macOS**: `./install.sh && ./run.sh`
   - **Windows**: `install.bat` 然后 `run.bat`
3. 浏览器访问 / Open browser: `https://127.0.0.1:5050`

### 🔄 从旧版本更新 / Update from Previous Version

- **Release 包用户**: 运行 `update.bat` 或 `./update.sh` / Run update script
- **Git 用户**: `git pull origin main` 后重跑 `install.bat` 或 `./install.sh` / Pull and re-run install

📖 **中文详细教程**: [查看 README](https://github.com/lueluelue12138/sharp-gui)

📖 **English Guide**: [View README.en.md](https://github.com/lueluelue12138/sharp-gui/blob/main/README.en.md)

Windows 完整便携包发布步骤

当用户要求发布 Windows 完整包、网盘包、一键打包、便携包、RTX 50 / CUDA 包时，优先使用项目根目录的一键入口：

build_portable_release.bat

默认行为：

• 默认从 version.txt 或 Git tag 自动提取版本号，生成包含真实版本号的包名。
• 若解析结果不像 vX.Y.Z，脚本默认会拒绝继续，避免误生成 local-* 测试包；测试时才使用 -AllowLocalVersion。
• 构建 React 前端。
• 前端构建会优先复用现有 frontend\node_modules，通过 Node 直接调用 TypeScript 与 Vite 入口；只有缺失或构建失败时才安装依赖，避免 npm 版本差异导致 lockfile 被改、npm ci 失败或 Windows .bin shim 权限问题。
• 使用主 venv 生成 cu128-rtx50 完整包。
• 使用主 venv 和 .video-reconstruction-env 生成 cu128-rtx50-video-recon 视频重建完整包。
• 自动准备 .portable-venvs\cu126 并生成 cu126-mainstream 完整包。
• 生成 .sha256.txt。
• 用 7-Zip 测试 ZIP 完整性。
• 生成 portable-dist\portable-release-template-<version>.md，用于复制到 GitHub Release 正文并填写网盘链接。
• 默认保留 .portable-venvs 作为下次打包加速缓存，并保留 portable-dist 中的历史旧版本产物；脚本结束时会打印缓存位置和手动清理命令。

常用命令：

build_portable_release.bat -Version v1.2.3
build_portable_release.bat -PlanOnly
build_portable_release.bat -Version v1.2.3 -PlanOnly
build_portable_release.bat -AllowLocalVersion -PlanOnly
build_portable_release.bat -SkipCu126
build_portable_release.bat -SkipCu128
build_portable_release.bat -SkipVideoRecon
build_portable_release.bat -CleanBuildVenvs
build_portable_release.bat -CleanOldArtifacts

清理策略：

• 默认保留最终产物：portable-dist\sharp-gui-*.zip、对应 .sha256.txt、portable-release-template-*.md。
• 默认保留 .portable-venvs 作为 cu126 打包加速缓存，避免每次重新下载和安装 PyTorch。
• 默认清理 .portable-build 临时 staging 目录，避免异常之外的中间目录残留。
• 默认保留旧版本 ZIP，避免误删历史发布包。
• 如需清理 cu126 打包缓存，可显式加 -CleanBuildVenvs，或手动删除 .portable-venvs。
• 如需清理旧版本便携包产物，可显式加 -CleanOldArtifacts，或手动删除 portable-dist 中不需要的版本。

根目录只保留 build_portable_release.bat 作为公开入口；tools/build_portable_package.ps1 是内部单包构建实现，除非用户明确要求调试单个目标包，否则不要让用户直接调用它。

发布检查清单：

• 确认 portable-dist\*.zip 与对应 .sha256.txt 已生成，且文件名包含真实版本号 vX.Y.Z，不能发布 local-* 或 v-local-test 包。
• 确认 portable-dist\portable-release-template-<version>.md 已生成，并将网盘链接补进去。
• cu128-rtx50 面向 RTX 50 系列核心包；cu128-rtx50-video-recon 面向 RTX 50 / CUDA 12.8 视频重建完整包；cu126-mainstream 面向 RTX 50 以下主流 NVIDIA 核心包。
• 首版完整便携包不提供纯 CPU 包。
• 不要把完整大 ZIP 上传到 GitHub Release 资产；GitHub Release 只贴网盘链接和 SHA256。
• 生成 commit message 或 release note 时，必须提到 Windows 完整便携包的适用显卡和校验方式。

规则

0. 提交代码之前，确保执行前端构建脚本 npm run build，生成最新的 dist/ 目录内容，并将其包含在 commit 中。这样可以确保发布版本包含最新的前端代码，让用户无需自行构建即可使用最新功能。
1. Pre-release 版本标题带 Pre-Release，正式版不带
2. Pre-release 需要顶部 > ⚠️ 警告 blockquote，正式版不需要
3. 章节标题使用 emoji: 🆕🎮📥🐛🔧📁🔄 等，按内容选择合适的
4. 每个 bullet 格式: - **粗体关键词**: 描述 / English desc
5. 如有从旧版升级的说明，加 ### 🔄 从旧版本更新 / Update 章节
6. 底部固定 Quick Start + README 链接
7. 不要写代码实现细节（如函数名、变量名），只写用户能感知的变化
8. 输出必须用 markdown 代码块包裹 (markdown ... )，方便用户复制
9. Pre-release 版本的更新指引中，update.bat/update.sh 必须加 --pre 参数（如 update.bat --pre 或 ./update.sh --pre），正式版不需要
10. 生成release note 前，先完整获取并整理上一个tag到目前main分支的所有commit message，确保release note的准确性和完整性
11. 生成正式版 release note前，完整获取并整理github上，上一个正式版本到目前最新的pre-release版本的release note，确保正式release note的准确性和完整性

Implement tasks from an OpenSpec change.

Input: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

Steps

1. Select the change

   If a name is provided, use it. Otherwise:

   • Infer from conversation context if the user mentioned a change
   • Auto-select if only one active change exists
   • If ambiguous, run openspec list --json to get available changes and use the AskUserQuestion tool to let the user select

   Always announce: "Using change: " and how to override (e.g., /opsx:apply <other>).

2. Check status to understand the schema

   openspec status --change "<name>" --json
   

   Parse the JSON to understand:

   • schemaName: The workflow being used (e.g., "spec-driven")
   • planningHome, changeRoot, and actionContext: planning scope and edit constraints
   • Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)

3. Get apply instructions

   openspec instructions apply --change "<name>" --json
   

   This returns:

   • contextFiles: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
   • Progress (total, complete, remaining)
   • Task list with status
   • Dynamic instruction based on current state

   Handle states:

   • If state: "blocked" (missing artifacts): show message, suggest using openspec-continue-change
   • If state: "all_done": congratulate, suggest archive
   • Otherwise: proceed to implementation

   Workspace guard: If status JSON reports actionContext.mode: "workspace-planning" and allowedEditRoots is empty, explain that full workspace apply is not supported in this slice. Treat linked repos and folders as read-only context, ask the user to select an affected area through an explicit implementation workflow, and STOP before editing files.

4. Read context files

   Read every file path listed under contextFiles from the apply instructions output. The files depend on the schema being used:

   • spec-driven: proposal, specs, design, tasks
   • Other schemas: follow the contextFiles from CLI output

5. Show current progress

   Display:

   • Schema being used
   • Progress: "N/M tasks complete"
   • Remaining tasks overview
   • Dynamic instruction from CLI

6. Implement tasks (loop until done or blocked)

   For each pending task:

   • Show which task is being worked on
   • Make the code changes required
   • Keep changes minimal and focused
   • Mark task complete in the tasks file: - [ ] → - [x]
   • Continue to next task

   Pause if:

   • Task is unclear → ask for clarification
   • Implementation reveals a design issue → suggest updating artifacts
   • Error or blocker encountered → report and wait for guidance
   • User interrupts

7. On completion or pause, show status

   Display:

   • Tasks completed this session
   • Overall progress: "N/M tasks complete"
   • If all done: suggest archive
   • If paused: explain why and wait for guidance

Output During Implementation

## Implementing: <change-name> (schema: <schema-name>)

Working on task 3/7: <task description>
[...implementation happening...]
✓ Task complete

Working on task 4/7: <task description>
[...implementation happening...]
✓ Task complete

Output On Completion

## Implementation Complete

**Change:** <change-name>
**Schema:** <schema-name>
**Progress:** 7/7 tasks complete ✓

### Completed This Session
- [x] Task 1
- [x] Task 2
...

All tasks complete! Ready to archive this change.

Output On Pause (Issue Encountered)

## Implementation Paused

**Change:** <change-name>
**Schema:** <schema-name>
**Progress:** 4/7 tasks complete

### Issue Encountered
<description of the issue>

**Options:**
1. <option 1>
2. <option 2>
3. Other approach

What would you like to do?

Guardrails

• Keep going through tasks until done or blocked
• Always read context files before starting (from the apply instructions output)
• If task is ambiguous, pause and ask before implementing
• If implementation reveals issues, pause and suggest artifact updates
• Keep code changes minimal and scoped to each task
• Update task checkbox immediately after completing each task
• Pause on errors, blockers, or unclear requirements - don't guess
• Use contextFiles from CLI output, don't assume specific file names

Fluid Workflow Integration

This skill supports the "actions on a change" model:

• Can be invoked anytime: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
• Allows artifact updates: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly

Archive a completed change in the experimental workflow.

Input: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

Steps

1. If no change name provided, prompt for selection

   Run openspec list --json to get available changes. Use the AskUserQuestion tool to let the user select.

   Show only active changes (not already archived). Include the schema used for each change if available.

   IMPORTANT: Do NOT guess or auto-select a change. Always let the user choose.

2. Check artifact completion status

   Run openspec status --change "<name>" --json to check artifact completion.

   Parse the JSON to understand:

   • schemaName: The workflow being used
   • planningHome, changeRoot, artifactPaths, and actionContext: path and scope context
   • artifacts: List of artifacts with their status (done or other)

   If status reports actionContext.mode: "workspace-planning", explain that workspace archive is not supported in this slice and STOP. Do not move workspace changes into repo-local archives or edit linked repos.

   If any artifacts are not done:

   • Display warning listing incomplete artifacts
   • Use AskUserQuestion tool to confirm user wants to proceed
   • Proceed if user confirms

3. Check task completion status

   Read the tasks file (typically tasks.md) to check for incomplete tasks.

   Count tasks marked with - [ ] (incomplete) vs - [x] (complete).

   If incomplete tasks found:

   • Display warning showing count of incomplete tasks
   • Use AskUserQuestion tool to confirm user wants to proceed
   • Proceed if user confirms

   If no tasks file exists: Proceed without task-related warning.

4. Assess delta spec sync state

   Use artifactPaths.specs.existingOutputPaths from status JSON to check for delta specs. If none exist, proceed without sync prompt.

   If delta specs exist:

   • Compare each delta spec with its corresponding main spec at openspec/specs/<capability>/spec.md
   • Determine what changes would be applied (adds, modifications, removals, renames)
   • Show a combined summary before prompting

   Prompt options:

   • If changes needed: "Sync now (recommended)", "Archive without syncing"
   • If already synced: "Archive now", "Sync anyway", "Cancel"

   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change ''. Delta spec analysis: "). Proceed to archive regardless of choice.

5. Perform the archive

   Create an archive directory under planningHome.changesDir if it doesn't exist:

   mkdir -p "<planningHome.changesDir>/archive"
   

   Generate target name using current date: YYYY-MM-DD-<change-name>

   Check if target already exists:

   • If yes: Fail with error, suggest renaming existing archive or using different date
   • If no: Move changeRoot to the archive directory

   mv "<changeRoot>" "<planningHome.changesDir>/archive/YYYY-MM-DD-<name>"
   

6. Display summary

   Show archive completion summary including:

   • Change name
   • Schema that was used
   • Archive location
   • Whether specs were synced (if applicable)
   • Note about any warnings (incomplete artifacts/tasks)

Output On Success

## Archive Complete

**Change:** <change-name>
**Schema:** <schema-name>
**Archived to:** the archive path derived from `planningHome.changesDir`/YYYY-MM-DD-<name>/
**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")

All artifacts complete. All tasks complete.

Guardrails

• Always prompt for change selection if not provided
• Use artifact graph (openspec status --json) for completion checking
• Don't block archive on warnings - just inform and confirm
• Preserve .openspec.yaml when moving to archive (it moves with the directory)
• Show clear summary of what happened
• If sync is requested, use openspec-sync-specs approach (agent-driven)
• If delta specs exist, always run the sync assessment and show the combined summary before prompting

Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.

IMPORTANT: Explore mode is for thinking, not implementing. You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.

This is a stance, not a workflow. There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.

The Stance

• Curious, not prescriptive - Ask questions that emerge naturally, don't follow a script
• Open threads, not interrogations - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
• Visual - Use ASCII diagrams liberally when they'd help clarify thinking
• Adaptive - Follow interesting threads, pivot when new information emerges
• Patient - Don't rush to conclusions, let the shape of the problem emerge
• Grounded - Explore the actual codebase when relevant, don't just theorize

What You Might Do

Depending on what the user brings, you might:

Explore the problem space

• Ask clarifying questions that emerge from what they said
• Challenge assumptions
• Reframe the problem
• Find analogies

Investigate the codebase

• Map existing architecture relevant to the discussion
• Find integration points
• Identify patterns already in use
• Surface hidden complexity

Compare options

• Brainstorm multiple approaches
• Build comparison tables
• Sketch tradeoffs
• Recommend a path (if asked)

Visualize

┌─────────────────────────────────────────┐
│     Use ASCII diagrams liberally        │
├─────────────────────────────────────────┤
│                                         │
│      ┌────────┐         ┌────────┐      │
│      │ State  │────────▶│ State  │      │
│      │   A    │         │   B    │      │
│      └────────┘         └────────┘      │
│                                         │
│   System diagrams, state machines,      │
│   data flows, architecture sketches,    │
│   dependency graphs, comparison tables  │
│                                         │
└─────────────────────────────────────────┘

Surface risks and unknowns

• Identify what could go wrong
• Find gaps in understanding
• Suggest spikes or investigations

OpenSpec Awareness

You have full context of the OpenSpec system. Use it naturally, don't force it.

Check for context

At the start, quickly check what exists:

openspec list --json

This tells you:

• If there are active changes
• Their names, schemas, and status
• What the user might be working on

When no change exists

Think freely. When insights crystallize, you might offer:

• "This feels solid enough to start a change. Want me to create a proposal?"
• Or keep exploring - no pressure to formalize

When a change exists

If the user mentions a change or you detect one is relevant:

1. Resolve and read existing artifacts for context

   • Run openspec status --change "<name>" --json.
   • Use changeRoot, artifactPaths, and actionContext from the status JSON.
   • Read existing files from artifactPaths.<artifact>.existingOutputPaths.

2. Reference them naturally in conversation

   • "Your design mentions using Redis, but we just realized SQLite fits better..."
   • "The proposal scopes this to premium users, but we're now thinking everyone..."

3. Offer to capture when decisions are made

   Insight Type	Where to Capture
   New requirement discovered	specs/<capability>/spec.md
   Requirement changed	specs/<capability>/spec.md
   Design decision made	design.md
   Scope changed	proposal.md
   New work identified	tasks.md
   Assumption invalidated	Relevant artifact

   Example offers:

   • "That's a design decision. Capture it in design.md?"
   • "This is a new requirement. Add it to specs?"
   • "This changes scope. Update the proposal?"

4. The user decides - Offer and move on. Don't pressure. Don't auto-capture.

What You Don't Have To Do

• Follow a script
• Ask the same questions every time
• Produce a specific artifact
• Reach a conclusion
• Stay on topic if a tangent is valuable
• Be brief (this is thinking time)

Handling Different Entry Points

User brings a vague idea:

User: I'm thinking about adding real-time collaboration

You: Real-time collab is a big space. Let me think about this...

      COLLABORATION SPECTRUM
      ════════════════════════════════════════════

      Awareness          Coordination         Sync
          │                   │                 │
          ▼                   ▼                 ▼
      ┌────────┐         ┌────────┐        ┌────────┐
      │Presence│         │Cursors │        │  CRDT  │
      │  "3    │         │ Multi  │        │Conflict│
      │online" │         │ select │        │  free  │
      └────────┘         └────────┘        └────────┘
          │                   │                 │
       trivial            moderate           complex

      Where's your head at?

User brings a specific problem:

User: The auth system is a mess

You: [reads codebase]

     ┌─────────────────────────────────────────────┐
     │              CURRENT AUTH FLOW              │
     └─────────────────────────────────────────────┘
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
     ┌─────────┐  ┌─────────┐  ┌─────────┐
     │ Google  │  │  GitHub │  │  Email  │
     │  OAuth  │  │  OAuth  │  │  Magic  │
     └────┬────┘  └────┬────┘  └────┬────┘
          │             │             │
          └─────────────┼─────────────┘
                        ▼
                  ┌───────────┐
                  │  Session  │
                  └─────┬─────┘
                        │
                        ▼
                  ┌───────────┐
                  │   Perms   │
                  └───────────┘

     I see three tangles. Which one's burning?

User is stuck mid-implementation:

User: /opsx:explore add-auth-system
      The OAuth integration is more complex than expected

You: [reads change artifacts]

     You're on task 4: "Implement OAuth flow"

     Let me trace what's involved...

     [draws diagram, explores options, suggests paths]

     Want to update the design to reflect this?
     Or add a spike task to investigate?

User wants to compare options:

User: Should we use Postgres or SQLite?

You: Generic answer is boring. What's the context?

User: A CLI tool that tracks local dev environments

You: That changes everything.

     ┌─────────────────────────────────────────────────┐
     │          CLI TOOL DATA STORAGE                  │
     └─────────────────────────────────────────────────┘

     Key constraints:
     • No daemon running
     • Must work offline
     • Single user

                  SQLite          Postgres
     Deployment   embedded ✓      needs server ✗
     Offline      yes ✓           no ✗
     Single file  yes ✓           no ✗

     SQLite. Not even close.

     Unless... is there a sync component?

Ending Discovery

There's no required ending. Discovery might:

• Flow into a proposal: "Ready to start? I can create a change proposal."
• Result in artifact updates: "Updated design.md with these decisions"
• Just provide clarity: User has what they need, moves on
• Continue later: "We can pick this up anytime"

When it feels like things are crystallizing, you might summarize:

## What We Figured Out

**The problem**: [crystallized understanding]

**The approach**: [if one emerged]

**Open questions**: [if any remain]

**Next steps** (if ready):
- Create a change proposal
- Keep exploring: just keep talking

But this summary is optional. Sometimes the thinking IS the value.

Guardrails

• Don't implement - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
• Don't fake understanding - If something is unclear, dig deeper
• Don't rush - Discovery is thinking time, not task time
• Don't force structure - Let patterns emerge naturally
• Don't auto-capture - Offer to save insights, don't just do it
• Do visualize - A good diagram is worth many paragraphs
• Do explore the codebase - Ground discussions in reality
• Do question assumptions - Including the user's and your own

Propose a new change - create the change and generate all artifacts in one step.

I'll create a change with artifacts:

• proposal.md (what & why)
• design.md (how)
• tasks.md (implementation steps)

When ready to implement, run /opsx:apply

Input: The user's request should include a change name (kebab-case) OR a description of what they want to build.

Steps

1. If no clear input provided, ask what they want to build

   Use the AskUserQuestion tool (open-ended, no preset options) to ask:

   "What change do you want to work on? Describe what you want to build or fix."

   From their description, derive a kebab-case name (e.g., "add user authentication" → add-user-auth).

   IMPORTANT: Do NOT proceed without understanding what the user wants to build.

2. Create the change directory

   openspec new change "<name>"
   

   This creates a scaffolded change in the planning home resolved by the CLI with .openspec.yaml.

3. Get the artifact build order

   openspec status --change "<name>" --json
   

   Parse the JSON to get:

   • applyRequires: array of artifact IDs needed before implementation (e.g., ["tasks"])
   • artifacts: list of all artifacts with their status and dependencies
   • planningHome, changeRoot, artifactPaths, and actionContext: path and scope context. Use these instead of assuming repo-local paths.

4. Create artifacts in sequence until apply-ready

   Use the TodoWrite tool to track progress through the artifacts.

   Loop through artifacts in dependency order (artifacts with no pending dependencies first):

   a. For each artifact that is ready (dependencies satisfied):

   • Get instructions:

     openspec instructions <artifact-id> --change "<name>" --json
     

   • The instructions JSON includes:
     • context: Project background (constraints for you - do NOT include in output)
     • rules: Artifact-specific rules (constraints for you - do NOT include in output)
     • template: The structure to use for your output file
     • instruction: Schema-specific guidance for this artifact type
     • resolvedOutputPath: Resolved path or pattern to write the artifact
     • dependencies: Completed artifacts to read for context
   • Read any completed dependency files for context
   • Create the artifact file using template as the structure and write it to resolvedOutputPath
   • Apply context and rules as constraints - but do NOT copy them into the file
   • Show brief progress: "Created "

   b. Continue until all applyRequires artifacts are complete

   • After creating each artifact, re-run openspec status --change "<name>" --json
   • Check if every artifact ID in applyRequires has status: "done" in the artifacts array
   • Stop when all applyRequires artifacts are done

   c. If an artifact requires user input (unclear context):

   • Use AskUserQuestion tool to clarify
   • Then continue with creation

5. Show final status

   openspec status --change "<name>"
   

Output

After completing all artifacts, summarize:

• Change name and location
• List of artifacts created with brief descriptions
• What's ready: "All artifacts created! Ready for implementation."
• Prompt: "Run /opsx:apply or ask me to implement to start working on the tasks."

Artifact Creation Guidelines

• Follow the instruction field from openspec instructions for each artifact type
• The schema defines what each artifact should contain - follow it
• Read dependency artifacts for context before creating new ones
• Use template as the structure for your output file - fill in its sections
• IMPORTANT: context and rules are constraints for YOU, not content for the file
  • Do NOT copy <context>, <rules>, <project_context> blocks into the artifact
  • These guide what you write, but should never appear in the output

Guardrails

• Create ALL artifacts needed for implementation (as defined by schema's apply.requires)
• Always read dependency artifacts before creating a new one
• If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
• If a change with that name already exists, ask if user wants to continue it or create a new one
• Verify each artifact file exists after writing before proceeding to next

Sync delta specs from a change to main specs.

This is an agent-driven operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).

Input: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.

Steps

1. If no change name provided, prompt for selection

   Run openspec list --json to get available changes. Use the AskUserQuestion tool to let the user select.

   Show changes that have delta specs (under specs/ directory).

   IMPORTANT: Do NOT guess or auto-select a change. Always let the user choose.

2. Resolve change context

   Run:

   openspec status --change "<name>" --json
   

   If status reports actionContext.mode: "workspace-planning", explain that workspace spec sync is not supported in this slice and STOP. Do not fall back to repo-local paths or edit linked repos.

3. Find delta specs

   Use artifactPaths.specs.existingOutputPaths from the status JSON as the list of delta spec files.

   Each delta spec file contains sections like:

   • ## ADDED Requirements - New requirements to add
   • ## MODIFIED Requirements - Changes to existing requirements
   • ## REMOVED Requirements - Requirements to remove
   • ## RENAMED Requirements - Requirements to rename (FROM:/TO: format)

   If no delta specs found, inform user and stop.

4. For each delta spec, apply changes to main specs

   For each repo-local capability delta spec path returned by the CLI:

   a. Read the delta spec to understand the intended changes

   b. Read the main spec at openspec/specs/<capability>/spec.md (may not exist yet)

   c. Apply changes intelligently:

   ADDED Requirements:

   • If requirement doesn't exist in main spec → add it
   • If requirement already exists → update it to match (treat as implicit MODIFIED)

   MODIFIED Requirements:

   • Find the requirement in main spec
   • Apply the changes - this can be:
     • Adding new scenarios (don't need to copy existing ones)
     • Modifying existing scenarios
     • Changing the requirement description
   • Preserve scenarios/content not mentioned in the delta

   REMOVED Requirements:

   • Remove the entire requirement block from main spec

   RENAMED Requirements:

   • Find the FROM requirement, rename to TO

   d. Create new main spec if capability doesn't exist yet:

   • Create openspec/specs/<capability>/spec.md
   • Add Purpose section (can be brief, mark as TBD)
   • Add Requirements section with the ADDED requirements

5. Show summary

   After applying all changes, summarize:

   • Which capabilities were updated
   • What changes were made (requirements added/modified/removed/renamed)

Delta Spec Format Reference

## ADDED Requirements

### Requirement: New Feature
The system SHALL do something new.

#### Scenario: Basic case
- **WHEN** user does X
- **THEN** system does Y

## MODIFIED Requirements

### Requirement: Existing Feature
#### Scenario: New scenario to add
- **WHEN** user does A
- **THEN** system does B

## REMOVED Requirements

### Requirement: Deprecated Feature

## RENAMED Requirements

- FROM: `### Requirement: Old Name`
- TO: `### Requirement: New Name`

Key Principle: Intelligent Merging

Unlike programmatic merging, you can apply partial updates:

• To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
• The delta represents intent, not a wholesale replacement
• Use your judgment to merge changes sensibly

Output On Success

## Specs Synced: <change-name>

Updated main specs:

**<capability-1>**:
- Added requirement: "New Feature"
- Modified requirement: "Existing Feature" (added 1 scenario)

**<capability-2>**:
- Created new spec file
- Added requirement: "Another Feature"

Main specs are now updated. The change remains active - archive when implementation is complete.

Guardrails

• Read both delta and main specs before making changes
• Preserve existing content not mentioned in delta
• If something is unclear, ask for clarification
• Show what you're changing as you go
• The operation should be idempotent - running twice should give same result

ui-ux-pro-max

Comprehensive design guide for web and mobile applications. Contains 67 styles, 161 color palettes, 57 font pairings, 99 UX guidelines, and 25 chart types across 16 technology stacks. Searchable database with priority-based recommendations.

Prerequisites

Check if Python is installed:

python3 --version || python --version

If Python is not installed, install it based on user's OS:

macOS:

brew install python3

Ubuntu/Debian:

sudo apt update && sudo apt install python3

Windows:

winget install Python.Python.3.12

How to Use This Skill

Use this skill when the user requests any of the following:

Follow this workflow:

Step 1: Analyze User Requirements

Extract key information from user request:

• Product type: 3D Gaussian Splatting GUI, local/NAS photo gallery, creator workflow dashboard, SaaS/admin/portfolio/landing page, or hybrid
• Target audience: Sharp GUI users working with image-to-3D workflows, generated 3D models, and local/NAS photo libraries; otherwise infer from the request
• Style keywords: Apple glass, professional, minimal, content-first, immersive 3D, gallery-focused, dark mode, etc.
• Stack: React + TypeScript + Vite with CSS Modules/CSS Variables for Sharp GUI; otherwise infer the requested stack

Step 2: Generate Design System (REQUIRED)

Always start with --design-system to get comprehensive recommendations with reasoning:

python3 skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]

This command:

1. Searches domains in parallel (product, style, color, landing, typography)
2. Applies reasoning rules from ui-reasoning.csv to select best matches
3. Returns complete design system: pattern, style, colors, typography, effects
4. Includes anti-patterns to avoid

Example:

python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"

Step 2b: Persist Design System (Master + Overrides Pattern)

To save the design system for hierarchical retrieval across sessions, add --persist:

python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name"

This creates:

• design-system/MASTER.md — Global Source of Truth with all design rules
• design-system/pages/ — Folder for page-specific overrides

With page-specific override:

python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" --page "dashboard"

This also creates:

• design-system/pages/dashboard.md — Page-specific deviations from Master

How hierarchical retrieval works:

1. When building a specific page (e.g., "Checkout"), first check design-system/pages/checkout.md
2. If the page file exists, its rules override the Master file
3. If not, use design-system/MASTER.md exclusively

Context-aware retrieval prompt:

I am building the [Page Name] page. Please read design-system/MASTER.md.
Also check if design-system/pages/[page-name].md exists.
If the page file exists, prioritize its rules.
If not, use the Master rules exclusively.
Now, generate the code...

Step 3: Supplement with Detailed Searches (as needed)

After getting the design system, use domain searches to get additional details:

python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]

When to use detailed searches:

Step 4: Stack Guidelines (Sharp GUI default: React)

Get implementation-specific best practices for the active stack:

python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack react

Search Reference

Available Domains

Available Stacks

Example Workflow

User request: "Make an AI search homepage。"

Step 1: Analyze Requirements

• Product type: Tool (3D model generation and photo gallery)
• Target audience: creators and operators managing image-to-3D generation workflows
• Style keywords: modern, minimal, content-first, dark mode
• Stack: React + TypeScript + Vite

Step 2: Generate Design System (REQUIRED)

python3 skills/ui-ux-pro-max/scripts/search.py "AI search tool modern minimal" --design-system -p "AI Search"

Output: Complete design system with pattern, style, colors, typography, effects, and anti-patterns.

Step 3: Supplement with Detailed Searches (as needed)

# Get style options for a modern tool product
python3 skills/ui-ux-pro-max/scripts/search.py "minimalism dark mode" --domain style

# Get UX best practices for search interaction and loading
python3 skills/ui-ux-pro-max/scripts/search.py "search loading animation" --domain ux

Step 4: Stack Guidelines

python3 skills/ui-ux-pro-max/scripts/search.py "list performance navigation" --stack react

Then: Synthesize design system + detailed searches and implement the design.

Output Formats

The --design-system flag supports two output formats:

# ASCII box (default) - best for terminal display
python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system

# Markdown - best for documentation
python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown

Tips for Better Results

Query Strategy

• Use multi-dimensional keywords — combine product + industry + tone + density: "entertainment social vibrant content-dense" not just "app"
• Try different keywords for the same need: "playful neon" → "vibrant dark" → "content-first minimal"
• Use --design-system first for full recommendations, then --domain to deep-dive any dimension you're unsure about
• Always add --stack react for implementation-specific guidance

Common Sticking Points

Pre-Delivery Checklist

• Run --domain ux "animation accessibility z-index loading" as a UX validation pass before implementation
• Run through Common Rules and the Pre-Delivery Checklist below as a final review
• Test on 375px (small phone) and landscape orientation
• Verify behavior with reduced-motion enabled and Dynamic Type at largest size
• Check dark mode contrast independently (don't assume light mode values work)
• Confirm all touch targets ≥44pt and no content hidden behind safe areas

Common Rules for Professional UI

These are frequently overlooked issues that make UI look unprofessional: Scope notice: The rules below cover app UI patterns; for Sharp GUI prioritize desktop-web and responsive browser interaction patterns.

Icons & Visual Elements

• 默认图标库使用 Phosphor (@phosphor-icons/react)。src/ui-ux-pro-max/data/icons.csv 中列出的只是常用推荐图标，不是完整集合。
• 当推荐表中找不到合适的图标时：
  • 优先继续从 Phosphor 的完整图标集中选择任何语义更贴切的图标；
  • 如果 Phosphor 也没有理想选项，可以使用 Heroicons (@heroicons/react) 作为备选，注意保持风格一致（线性/填充、笔画粗细、圆角风格）。

Interaction (App)

Light/Dark Mode Contrast

Layout & Spacing

Pre-Delivery Checklist

Before delivering UI code, verify these items: Scope notice: This checklist is for app UI quality; for Sharp GUI prioritize desktop-web and responsive browser quality.

Visual Quality

• No emojis used as icons (use SVG instead)
• All icons come from a consistent icon family and style
• Official brand assets are used with correct proportions and clear space
• Pressed-state visuals do not shift layout bounds or cause jitter
• Semantic theme tokens are used consistently (no ad-hoc per-screen hardcoded colors)

Interaction

• All tappable elements provide clear pressed feedback (ripple/opacity/elevation)
• Touch targets meet minimum size (>=44x44pt iOS, >=48x48dp Android)
• Micro-interaction timing stays in the 150-300ms range with native-feeling easing
• Disabled states are visually clear and non-interactive
• Screen reader focus order matches visual order, and interactive labels are descriptive
• Gesture regions avoid nested/conflicting interactions (tap/drag/back-swipe conflicts)

Light/Dark Mode

• Primary text contrast >=4.5:1 in both light and dark mode
• Secondary text contrast >=3:1 in both light and dark mode
• Dividers/borders and interaction states are distinguishable in both modes
• Modal/drawer scrim opacity is strong enough to preserve foreground legibility (typically 40-60% black)
• Both themes are tested before delivery (not inferred from a single theme)

Layout

• Safe areas are respected for headers, tab bars, and bottom CTA bars
• Scroll content is not hidden behind fixed/sticky bars
• Verified on small phone, large phone, and tablet (portrait + landscape)
• Horizontal insets/gutters adapt correctly by device size and orientation
• 4/8dp spacing rhythm is maintained across component, section, and page levels
• Long-form text measure remains readable on larger devices (no edge-to-edge paragraphs)

Accessibility

• All meaningful images/icons have accessibility labels
• Form fields have labels, hints, and clear error messages
• Color is not the only indicator
• Reduced motion and dynamic text size are supported without layout breakage
• Accessibility traits/roles/states (selected, disabled, expanded) are announced correctly