@superspec/cli 1.0.0

package/templates/en/commands/ss-apply.md

@@ -0,0 +1,19 @@
+---
+name: /ss-apply
+id: ss-apply
+category: SuperSpec
+description: Implement tasks from the current change
+---
+<!-- SUPERSPEC:START -->
+**Guardrails**
+- Read tasks.md before implementing
+- Implement one task at a time, mark as COMPLETE after verification
+- Run tests/lint after each significant change
+- Never implement without reading the spec first (in boost mode)
+
+**Steps**
+1. Read `{specDir}/changes/<name>/tasks.md`
+2. If boost mode, also read `spec.md` and `checklist.md`
+3. For each task: update status → implement → verify → mark COMPLETE
+4. Run full test suite after all tasks complete
+<!-- SUPERSPEC:END -->

package/templates/en/commands/ss-archive.md

@@ -0,0 +1,15 @@
+---
+name: /ss-archive
+id: ss-archive
+category: SuperSpec
+description: Archive completed change
+---
+<!-- SUPERSPEC:START -->
+**Guardrails**
+- Only archive when all tasks are COMPLETE
+- Ensure tests pass before archiving
+
+**Steps**
+1. Verify all tasks in tasks.md are marked COMPLETE
+2. Run `superspec archive <name>` or `superspec archive --all`
+<!-- SUPERSPEC:END -->

package/templates/en/commands/ss-checklist.md

@@ -0,0 +1,16 @@
+---
+name: /ss-checklist
+id: ss-checklist
+category: SuperSpec
+description: Quality gate before apply (boost mode)
+---
+<!-- SUPERSPEC:START -->
+**Guardrails**
+- Only applicable in boost mode
+- Validate all quality criteria before implementation
+
+**Steps**
+1. Read `{specDir}/changes/<name>/checklist.md`
+2. Verify each checklist item
+3. Address any failing checks before /ss-apply
+<!-- SUPERSPEC:END -->

package/templates/en/commands/ss-clarify.md

@@ -0,0 +1,17 @@
+---
+name: /ss-clarify
+id: ss-clarify
+category: SuperSpec
+description: Resolve ambiguity and record decisions
+---
+<!-- SUPERSPEC:START -->
+**Guardrails**
+- Add Q&A to clarify.md when requirements are ambiguous
+- Record decisions with reasoning
+
+**Steps**
+1. Identify the ambiguous point or question
+2. Ask user for clarification
+3. Record the Q&A in `{specDir}/changes/<name>/clarify.md`
+4. Update proposal.md or spec.md if needed
+<!-- SUPERSPEC:END -->

package/templates/en/commands/ss-create.md

@@ -0,0 +1,19 @@
+---
+name: /ss-create
+id: ss-create
+category: SuperSpec
+description: Create a new change with proposal (boost mode adds spec + checklist)
+---
+<!-- SUPERSPEC:START -->
+**Guardrails**
+- Read `superspec.config.json` first to get `lang`, `specDir`, `boost`, `strategy`, `context`
+- Check existing changes in `{specDir}/changes/` to avoid duplicates
+- Never create change folders manually — use `superspec create <name>` CLI
+- Do not write any code during the proposal stage. Only create design documents
+
+**Steps**
+1. Run `superspec create <name> [-b] [-c] [-d <description>]` to scaffold the change
+2. If boost mode (-b), also generate spec.md and checklist.md
+3. Read the generated proposal.md and understand the change scope
+4. Wait for user confirmation before proceeding to /ss-tasks
+<!-- SUPERSPEC:END -->

package/templates/en/commands/ss-deps.md

@@ -0,0 +1,11 @@
+---
+name: /ss-deps
+id: ss-deps
+category: SuperSpec
+description: View dependency graph
+---
+<!-- SUPERSPEC:START -->
+**Steps**
+1. Run `superspec deps [name]`
+2. Review dependency tree
+<!-- SUPERSPEC:END -->

package/templates/en/commands/ss-link.md

@@ -0,0 +1,11 @@
+---
+name: /ss-link
+id: ss-link
+category: SuperSpec
+description: Add spec dependency
+---
+<!-- SUPERSPEC:START -->
+**Steps**
+1. Run `superspec link <name> --depends-on <other>`
+2. This updates the frontmatter: `depends_on: [other]`
+<!-- SUPERSPEC:END -->

package/templates/en/commands/ss-lint.md

@@ -0,0 +1,15 @@
+---
+name: /ss-lint
+id: ss-lint
+category: SuperSpec
+description: Check artifact line limits
+---
+<!-- SUPERSPEC:START -->
+**Guardrails**
+- Target: < 300 lines per artifact
+- Hard limit: 400 lines
+
+**Steps**
+1. Run `superspec lint [name]`
+2. If exceeds limit, split into smaller artifacts
+<!-- SUPERSPEC:END -->

package/templates/en/commands/ss-resume.md

@@ -0,0 +1,17 @@
+---
+name: /ss-resume
+id: ss-resume
+category: SuperSpec
+description: Restore spec context for vibe coding
+---
+<!-- SUPERSPEC:START -->
+**Guardrails**
+- Use when returning to a change after a break
+- Read context.md first if it exists
+
+**Steps**
+1. Run `superspec sync` to collect git diff into context.md
+2. Read `{specDir}/changes/<name>/context.md`
+3. Read current proposal.md and tasks.md to understand state
+4. Identify incomplete tasks and continue implementation
+<!-- SUPERSPEC:END -->

package/templates/en/commands/ss-search.md

@@ -0,0 +1,12 @@
+---
+name: /ss-search
+id: ss-search
+category: SuperSpec
+description: Full-text search across changes
+---
+<!-- SUPERSPEC:START -->
+**Steps**
+1. Run `superspec search <query>`
+2. Use `--archived` to include archived changes
+3. Use `--artifact <type>` to filter by artifact type
+<!-- SUPERSPEC:END -->

package/templates/en/commands/ss-status.md

@@ -0,0 +1,12 @@
+---
+name: /ss-status
+id: ss-status
+category: SuperSpec
+description: View all change statuses
+---
+<!-- SUPERSPEC:START -->
+**Steps**
+1. Run `superspec status` to list all changes
+2. Review status: Draft → Ready → Done
+3. Check dependencies between changes
+<!-- SUPERSPEC:END -->

package/templates/en/commands/ss-tasks.md

@@ -0,0 +1,19 @@
+---
+name: /ss-tasks
+id: ss-tasks
+category: SuperSpec
+description: Generate task list from proposal
+---
+<!-- SUPERSPEC:START -->
+**Guardrails**
+- Read proposal.md first (and spec.md in boost mode)
+- Tasks must be small, verifiable, and actionable (< 1 hour each in boost mode)
+- Group related changes to the same file under one task
+- Include verification steps for each task
+
+**Steps**
+1. Read `{specDir}/changes/<name>/proposal.md`
+2. If boost mode, also read `spec.md`
+3. Generate tasks.md with phased implementation steps
+4. Each task should have: clear description, file paths, dependencies, verification criteria
+<!-- SUPERSPEC:END -->

package/templates/en/commands/ss-validate.md

@@ -0,0 +1,15 @@
+---
+name: /ss-validate
+id: ss-validate
+category: SuperSpec
+description: Cross-reference consistency check (boost mode)
+---
+<!-- SUPERSPEC:START -->
+**Guardrails**
+- Validate US↔FR↔AC↔tasks consistency
+- Only applicable in boost mode
+
+**Steps**
+1. Run `superspec validate [name]`
+2. Fix any consistency errors reported
+<!-- SUPERSPEC:END -->

package/templates/en/proposal.md

@@ -0,0 +1,53 @@
+---
+name: {{name}}
+status: draft
+strategy: {{strategy}}
+depends_on: []
+---
+
+# Proposal: {{name}}
+
+> Created: {{date}}
+
+## Background
+
+<!-- Why this change? What problem exists? -->
+
+## Goals
+
+<!-- What should this change achieve? -->
+
+- [ ] Goal 1
+- [ ] Goal 2
+
+## Non-Goals
+
+<!-- What is explicitly out of scope -->
+
+## Solution Overview
+
+<!-- High-level solution description -->
+
+## Impact Scope
+
+<!-- Which modules/files/systems are affected? -->
+
+- **Modules**:
+- **Files**:
+- **Dependencies**:
+
+## Risks & Trade-offs
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+|      |        |            |
+
+## Open Questions
+
+<!-- Questions that need further discussion -->
+
+1.
+
+---
+
+**Status**: 🟡 Draft

package/templates/en/spec.md

@@ -0,0 +1,73 @@
+---
+name: {{name}}
+status: draft
+strategy: {{strategy}}
+depends_on: []
+---
+
+# Specification: {{name}}
+
+> Created: {{date}}
+
+## Overview
+
+<!-- Brief description of this change -->
+
+## User Stories
+
+### US-1: [Story Title]
+
+**As a** [role], **I want to** [feature], **so that** [value]
+
+#### Acceptance Criteria
+
+- [ ] AC-1.1:
+- [ ] AC-1.2:
+
+### US-2: [Story Title]
+
+**As a** [role], **I want to** [feature], **so that** [value]
+
+#### Acceptance Criteria
+
+- [ ] AC-2.1:
+- [ ] AC-2.2:
+
+## Functional Requirements
+
+### FR-1: [Requirement Title]
+
+- **Description**:
+- **Priority**: P0 / P1 / P2
+- **Dependencies**:
+
+### FR-2: [Requirement Title]
+
+- **Description**:
+- **Priority**: P0 / P1 / P2
+- **Dependencies**:
+
+## Non-Functional Requirements
+
+- **Performance**:
+- **Security**:
+- **Compatibility**:
+
+## Data Model
+
+<!-- Describe data structure changes if needed -->
+
+## API Design
+
+<!-- Describe API design if needed -->
+
+## Edge Cases
+
+<!-- Edge cases to consider -->
+
+1.
+2.
+
+---
+
+**Status**: 🟡 Draft

package/templates/en/tasks.md

@@ -0,0 +1,52 @@
+---
+name: {{name}}
+status: draft
+strategy: {{strategy}}
+depends_on: []
+---
+
+# Task List: {{name}}
+
+> Created: {{date}}
+
+## Phase 1: Infrastructure
+
+- [ ] 1.1 [Task description]
+  - File: `path/to/file`
+  - Depends: none
+- [ ] 1.2 [Task description]
+  - File: `path/to/file`
+  - Depends: 1.1
+
+## Phase 2: Core Implementation
+
+- [ ] 2.1 [Task description]
+  - File: `path/to/file`
+  - Depends: Phase 1
+- [ ] 2.2 [Task description] `[P]`
+  - File: `path/to/file`
+  - Depends: 2.1
+- [ ] 2.3 [Task description] `[P]`
+  - File: `path/to/file`
+  - Depends: 2.1
+
+## Phase 3: Integration & Verification
+
+- [ ] 3.1 [Task description]
+  - File: `path/to/file`
+  - Depends: Phase 2
+- [ ] 3.2 [Task description]
+  - File: `path/to/file`
+  - Depends: 3.1
+
+## Checkpoints
+
+- [ ] Phase 1 complete, foundation ready
+- [ ] Phase 2 complete, core features ready
+- [ ] Phase 3 complete, integration verified
+
+---
+
+`[P]` = Can be executed in parallel
+
+**Status**: 🟡 Pending

package/templates/zh/checklist.md

@@ -0,0 +1,62 @@
+---
+name: {{name}}
+status: draft
+strategy: {{strategy}}
+depends_on: []
+---
+
+# 质量检查清单: {{name}}
+
+> 创建日期: {{date}}
+> 模式: 增强 (boost)
+
+## 需求完整性
+
+- [ ] 所有用户故事都有明确的验收标准
+- [ ] 功能需求覆盖了所有用户故事
+- [ ] 非功能需求已定义（性能、安全、兼容性）
+- [ ] 边界情况已识别并记录
+- [ ] 数据模型变更已描述
+
+## 提案质量
+
+- [ ] 背景和动机清晰
+- [ ] 目标可衡量
+- [ ] 非目标明确
+- [ ] 风险已识别并有缓解措施
+- [ ] 影响范围已评估
+
+## 规格一致性
+
+- [ ] spec 与 proposal 目标一致
+- [ ] 用户故事覆盖 proposal 中所有目标
+- [ ] 验收标准可测试
+- [ ] 无矛盾需求
+- [ ] 依赖关系明确
+
+## 任务可执行性
+
+- [ ] 任务粒度合理（每个 < 2h）
+- [ ] 依赖关系正确
+- [ ] 并行任务标记正确
+- [ ] 文件路径明确
+- [ ] 检查点设置合理
+
+## 交叉验证
+
+- [ ] proposal → spec: 所有目标都有对应需求
+- [ ] spec → tasks: 所有需求都有对应任务
+- [ ] tasks → spec: 没有超出 spec 范围的任务
+- [ ] clarify → all: 所有澄清结果已更新到相关文档
+
+## 实现就绪度
+
+- [ ] 技术方案可行
+- [ ] 无阻塞依赖
+- [ ] 开放问题已解决（或已标记为非阻塞）
+- [ ] 团队对方案达成共识
+
+---
+
+**总分**: _ / 25
+**状态**: 🟡 待检查

package/templates/zh/clarify.md

@@ -0,0 +1,44 @@
+---
+name: {{name}}
+status: draft
+strategy: {{strategy}}
+depends_on: []
+---
+
+# 澄清记录: {{name}}
+
+> 创建日期: {{date}}
+
+## 澄清问题
+
+### Q1: [问题]
+
+- **提问方**: AI / 用户
+- **回答**:
+- **影响**: 对 spec / proposal / tasks 的影响
+- **已更新**: ☐ spec ☐ proposal ☐ tasks
+
+### Q2: [问题]
+
+- **提问方**: AI / 用户
+- **回答**:
+- **影响**:
+- **已更新**: ☐ spec ☐ proposal ☐ tasks
+
+## 决策记录
+
+| # | 决策 | 原因 | 日期 |
+|---|------|------|------|
+| D1 |    |      |      |
+| D2 |    |      |      |
+
+## 待澄清
+
+<!-- 尚未解决的问题 -->
+
+1.
+2.
+
+---
+
+**状态**: 🟡 进行中

package/templates/zh/commands/ss-apply.md

@@ -0,0 +1,19 @@
+---
+name: /ss-apply
+id: ss-apply
+category: SuperSpec
+description: 执行变更任务
+---
+<!-- SUPERSPEC:START -->
+**Guardrails**
+- 执行前先读取 tasks.md
+- 一次执行一个任务，验证后标记为 COMPLETE
+- 每次重大变更后运行测试/检查
+- boost 模式下必须先读取 spec 再执行
+
+**Steps**
+1. 读取 `{specDir}/changes/<name>/tasks.md`
+2. boost 模式下，同时读取 `spec.md` 和 `checklist.md`
+3. 对每个任务：更新状态 → 执行 → 验证 → 标记 COMPLETE
+4. 所有任务完成后运行完整测试套件
+<!-- SUPERSPEC:END -->

package/templates/zh/commands/ss-archive.md

@@ -0,0 +1,15 @@
+---
+name: /ss-archive
+id: ss-archive
+category: SuperSpec
+description: 归档已完成的变更
+---
+<!-- SUPERSPEC:START -->
+**Guardrails**
+- 只有所有任务都 COMPLETE 后才能归档
+- 归档前确保测试通过
+
+**Steps**
+1. 确认 tasks.md 中所有任务都标记为 COMPLETE
+2. 运行 `superspec archive <name>` 或 `superspec archive --all`
+<!-- SUPERSPEC:END -->

package/templates/zh/commands/ss-checklist.md

@@ -0,0 +1,16 @@
+---
+name: /ss-checklist
+id: ss-checklist
+category: SuperSpec
+description: apply 前的质量门（boost 模式）
+---
+<!-- SUPERSPEC:START -->
+**Guardrails**
+- 仅在 boost 模式下适用
+- 执行前验证所有质量标准
+
+**Steps**
+1. 读取 `{specDir}/changes/<name>/checklist.md`
+2. 验证每个检查项
+3. 在 /ss-apply 前解决所有失败检查
+<!-- SUPERSPEC:END -->

package/templates/zh/commands/ss-clarify.md

@@ -0,0 +1,17 @@
+---
+name: /ss-clarify
+id: ss-clarify
+category: SuperSpec
+description: 澄清歧义、记录决策
+---
+<!-- SUPERSPEC:START -->
+**Guardrails**
+- 当需求不明确时，向 clarify.md 添加 Q&A
+- 记录决策及理由
+
+**Steps**
+1. 识别模糊点或问题
+2. 向用户询问澄清
+3. 将 Q&A 记录到 `{specDir}/changes/<name>/clarify.md`
+4. 根据需要更新 proposal.md 或 spec.md
+<!-- SUPERSPEC:END -->

package/templates/zh/commands/ss-create.md

@@ -0,0 +1,19 @@
+---
+name: /ss-create
+id: ss-create
+category: SuperSpec
+description: 创建变更 + 生成 proposal（boost 模式额外生成 spec + checklist）
+---
+<!-- SUPERSPEC:START -->
+**Guardrails**
+- 首先读取 `superspec.config.json` 获取 `lang`, `specDir`, `boost`, `strategy`, `context`
+- 检查 `{specDir}/changes/` 中现有变更，避免重复
+- 永远不要手动创建变更文件夹 —— 使用 `superspec create <name>` CLI
+- 在提案阶段不要编写任何代码，只创建设计文档
+
+**Steps**
+1. 运行 `superspec create <name> [-b] [-c] [-d <description>]` 创建变更结构
+2. 如果是 boost 模式 (-b)，额外生成 spec.md 和 checklist.md
+3. 读取生成的 proposal.md 理解变更范围
+4. 等待用户确认后再继续 /ss-tasks
+<!-- SUPERSPEC:END -->

package/templates/zh/commands/ss-deps.md

@@ -0,0 +1,11 @@
+---
+name: /ss-deps
+id: ss-deps
+category: SuperSpec
+description: 查看依赖图
+---
+<!-- SUPERSPEC:START -->
+**Steps**
+1. 运行 `superspec deps [name]`
+2. 查看依赖树
+<!-- SUPERSPEC:END -->

package/templates/zh/commands/ss-link.md

@@ -0,0 +1,11 @@
+---
+name: /ss-link
+id: ss-link
+category: SuperSpec
+description: 添加 spec 依赖
+---
+<!-- SUPERSPEC:START -->
+**Steps**
+1. 运行 `superspec link <name> --depends-on <other>`
+2. 这会更新 frontmatter: `depends_on: [other]`
+<!-- SUPERSPEC:END -->

package/templates/zh/commands/ss-lint.md

@@ -0,0 +1,15 @@
+---
+name: /ss-lint
+id: ss-lint
+category: SuperSpec
+description: 检查 artifact 大小
+---
+<!-- SUPERSPEC:START -->
+**Guardrails**
+- 目标：每个 artifact < 300 行
+- 硬限制：400 行
+
+**Steps**
+1. 运行 `superspec lint [name]`
+2. 如果超出限制，拆分为更小的 artifact
+<!-- SUPERSPEC:END -->

package/templates/zh/commands/ss-resume.md

@@ -0,0 +1,17 @@
+---
+name: /ss-resume
+id: ss-resume
+category: SuperSpec
+description: 恢复 spec 上下文（用于 vibe coding）
+---
+<!-- SUPERSPEC:START -->
+**Guardrails**
+- 中断后返回工作时使用
+- 优先读取 context.md（如果存在）
+
+**Steps**
+1. 运行 `superspec sync` 将 git 变更收集到 context.md
+2. 读取 `{specDir}/changes/<name>/context.md`
+3. 读取当前的 proposal.md 和 tasks.md 了解状态
+4. 识别未完成的任务并继续执行
+<!-- SUPERSPEC:END -->

package/templates/zh/commands/ss-search.md

@@ -0,0 +1,12 @@
+---
+name: /ss-search
+id: ss-search
+category: SuperSpec
+description: 全文搜索变更
+---
+<!-- SUPERSPEC:START -->
+**Steps**
+1. 运行 `superspec search <query>`
+2. 使用 `--archived` 包含已归档的变更
+3. 使用 `--artifact <type>` 按 artifact 类型过滤
+<!-- SUPERSPEC:END -->

package/templates/zh/commands/ss-status.md

@@ -0,0 +1,12 @@
+---
+name: /ss-status
+id: ss-status
+category: SuperSpec
+description: 查看所有变更状态
+---
+<!-- SUPERSPEC:START -->
+**Steps**
+1. 运行 `superspec status` 列出所有变更
+2. 查看状态：Draft → Ready → Done
+3. 检查变更间的依赖关系
+<!-- SUPERSPEC:END -->