@superspec/cli 1.0.0 → 1.1.0

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

@@ -2,18 +2,100 @@
 name: /ss-create
 id: ss-create
 category: SuperSpec
-description: Create a new change with proposal (boost mode adds spec + checklist)
+description: Create or update the feature specification from a natural language feature with proposal (boost mode adds spec + checklist)
 ---
 <!-- SUPERSPEC:START -->
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+The text the user typed after `/ss-create` **is** the feature description. Do not ask the user to repeat it unless they provided an empty command.
+
 **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
+- Read `superspec.config.json` first → get `lang`, `specDir`, `boost`, `strategy`, `context`, `branchPrefix`, `branchTemplate`, `changeNameTemplate`
+- **Pre-task review** (refer to AGENTS.md "Before ANY Task"):
+  - Read `context` files, README, architecture docs
+  - Inspect `{specDir}/changes/` → avoid duplicate changes via `depends_on`
+- Never create change folders manually — use `superspec create <feature>` CLI
 - Do not write any code during the proposal stage. Only create design documents
 
+**Input Parsing Rules**
+
+From user input, extract three things: **feature name**, **intent type**, **developer**, **lang**.
+
+| Extract | Rule | Example |
+|---------|------|---------|
+| Feature name | Convert to camelCase. Chinese → translate to English first | "add user auth" → `addUserAuth`; "添加用户认证" → `addUserAuth` |
+| Intent type | Semantic inference from input | add/new/implement → `feature`; fix/bug/hotfix → `hotfix`; refactor/optimize → `refactor`; docs → `docs`; test → `test`; build/deps → `chore`; default → `feature` |
+| Developer | "@username" or "Developer: xxx" → extract (remove "@"). Fallback: git user name | "添加todolist @jay" → user=`jay` |
+| Lang | CJK chars → `zh`; explicit "zh"/"中文" → `zh`; "en"/"English" → `en`; fallback: config `lang` | "添加todolist" → `zh` |
+
+**Naming Templates**
+
+Config supports custom templates with variables `{date}`, `{feature}`, `{user}`, `{intentType}`, `{prefix}`:
+- `branchTemplate` (default: `{intentType}-{date}-{feature}-{user}`)
+- `changeNameTemplate` (default: `{intentType}-{date}-{feature}-{user}`)
+
+```bash
+# "添加todolist @jay" → feature=addTodolist, user=jay, intentType=feature, lang=zh
+superspec create addTodolist --intent-type feature --lang zh
+# Branch: feature-20260212-addTodolist-jay
+
+# "fix login bug" → feature=fixLoginBug, intentType=hotfix, user=<git username>
+superspec create fixLoginBug --intent-type hotfix
+# Branch: hotfix-20260212-fixLoginBug-gitusername
+```
+
+If user provides custom `--branch-prefix`, prepend to template.
+
+**CLI Command Structure**
+```bash
+superspec create <feature> [options]
+  -b, --boost                          Boost mode (spec + checklist)
+  -c, --creative                       Creative mode (explore new solutions)
+  -d, --description <desc>             Change description
+  --no-branch                          Skip git branch creation
+  --spec-dir <dir>                     Custom spec folder
+  --branch-prefix <prefix>             Custom branch prefix
+  --branch-template <template>         Override branch name template
+  --change-name-template <template>    Override folder name template
+  --intent-type <type>                 Intent type (feature, hotfix, bugfix, refactor, chore)
+  --feature <feature>                  Feature name
+  --user <user>                        Developer identifier
+  --lang <lang>                        SDD Document Language (en, zh)
+```
+
+**When to use design.md** (optional, boost mode):
+- Solution spans multiple systems or introduces new architectural patterns
+- Major architectural decisions with significant trade-offs
+- Cross-team architecture alignment needed
+
+**Spec Capability Splitting** (recommended for large changes):
+When a change involves multiple independent capabilities, split by domain:
+```
+{specDir}/changes/<name>/
+├── proposal.md
+├── design.md      (optional)
+├── specs/
+│   ├── auth/spec.md
+│   ├── api/spec.md
+│   └── ui/spec.md
+├── tasks.md
+└── checklist.md
+```
+Each spec.md < 300 lines. Outline domains in proposal.md, group tasks by domain in tasks.md.
+
 **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
+1. Parse user input → extract feature (camelCase), intent type, developer, lang
+2. Run: `superspec create <feature> --intent-type <type> [--lang <lang>] [--user <user>]`
+3. Pre-task review: read project context, check existing changes, understand dependencies
+4. Assess complexity: if multiple independent capability domains → consider splitting spec
+5. Read generated proposal.md → understand scope; if design.md needed → clarify architectural decisions
+6. Wait for user confirmation before proceeding to /ss-tasks
 <!-- SUPERSPEC:END -->

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

@@ -6,6 +6,7 @@ description: Add spec dependency
 ---
 <!-- SUPERSPEC:START -->
 **Steps**
-1. Run `superspec link <name> --depends-on <other>`
+1. Run `superspec deps add <name> --on <other>`
 2. This updates the frontmatter: `depends_on: [other]`
+3. Verify: `superspec deps list <name>`
 <!-- SUPERSPEC:END -->

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

@@ -0,0 +1,54 @@
+---
+name: /ss-specs
+id: ss-specs
+category: SuperSpec
+description: Create multi-capability spec structure for large changes
+---
+<!-- SUPERSPEC:START -->
+**Purpose**
+When spec.md may exceed 300 lines due to multiple independent capability domains, split into capability-specific spec files.
+
+**When to Split**
+- Change spans multiple system modules (e.g., auth + API + UI)
+- Single spec.md expected to exceed 300 lines
+- Need parallel development of independent capabilities
+
+**When NOT to Split**
+- Single module change or spec.md < 200 lines
+- Capabilities are tightly coupled
+- Rapid prototyping or experimental changes
+
+**Capability Domain Types**
+`auth` (authentication/authorization) · `api` (REST/GraphQL) · `ui` (frontend) · `data` (models/schema) · `workflow` (business processes) · `integration` (external systems) · `infra` (deployment)
+
+**Spec Template**
+```markdown
+---
+name: <name>-<capability>
+status: draft
+strategy: {{strategy}}
+depends_on: []
+capability: <capability-name>
+---
+# Spec: <name> - <Capability>
+
+## Capability Scope
+## User Stories
+### US-<capability>-1: [Title]
+## Functional Requirements
+### FR-<capability>-1: [Title]
+## Cross-Capability Dependencies
+- Depends on `auth/spec.md` FR-auth-2
+- Provides API-1 for `ui/spec.md`
+## Edge Cases
+```
+
+**ID Convention**: `US-<cap>-<n>`, `FR-<cap>-<n>`, `AC-<cap>-<n>.<sub>`
+
+**Steps**
+1. Identify 2-5 independent capability domains in proposal.md
+2. Create `specs/<capability>/spec.md` for each, using template above
+3. Document splitting rationale in design.md
+4. Group tasks by capability in tasks.md
+5. Validate: clear boundaries, explicit dependencies, each spec < 300 lines, IDs follow convention
+<!-- SUPERSPEC:END -->

package/templates/en/design.md

@@ -0,0 +1,126 @@
+---
+name: {{name}}
+status: draft
+strategy: {{strategy}}
+depends_on: []
+---
+
+# Architecture Design: {{name}}
+
+> Created: {{date}}
+
+## Design Goals
+
+<!-- Describe the core objectives of this architectural design -->
+
+## System Scope
+
+<!-- Define system/module boundaries affected by this change -->
+
+- **Affected Systems**:
+- **Affected Modules**:
+- **Out of Scope**:
+
+## Architecture Decisions
+
+### Decision 1: [Decision Title]
+
+**Context**: Why is this decision needed?
+
+**Options Considered**:
+- **Option A**: [Description]
+  - Pros:
+  - Cons:
+- **Option B**: [Description]
+  - Pros:
+  - Cons:
+
+**Decision**: [Chosen option]
+
+**Rationale**: [Why this option was chosen]
+
+### Decision 2: [Decision Title]
+
+**Context**:
+
+**Options Considered**:
+- **Option A**:
+- **Option B**:
+
+**Decision**:
+
+**Rationale**:
+
+## Architecture Diagram
+
+<!-- Use mermaid or text to describe key architecture -->
+
+```mermaid
+graph TD
+    A[Component A] --> B[Component B]
+    B --> C[Component C]
+```
+
+## Data Flow
+
+<!-- Describe critical data flow paths -->
+
+1. User Request →
+2. Processing Layer →
+3. Storage Layer →
+4. Response
+
+## Technology Stack
+
+<!-- If introducing new technologies, explain rationale -->
+
+| Technology | Version | Purpose | Rationale |
+|------------|---------|---------|-----------|
+| |  |  |  |
+
+## Performance Impact
+
+- **Expected Performance Changes**:
+- **Potential Bottlenecks**:
+- **Optimization Strategies**:
+
+## Security Considerations
+
+- **Authentication**:
+- **Authorization**:
+- **Data Encryption**:
+- **Audit Logging**:
+
+## Scalability Considerations
+
+- **Horizontal Scaling**:
+- **Vertical Scaling**:
+- **Future Evolution Path**:
+
+## Migration Strategy
+
+<!-- If major architectural changes, describe migration steps -->
+
+1. **Phase 1**:
+2. **Phase 2**:
+3. **Phase 3**:
+
+**Rollback Plan**:
+
+## Risks & Mitigation
+
+| Risk | Impact | Probability | Mitigation |
+|------|--------|-------------|------------|
+| | | | |
+
+## Dependencies
+
+<!-- Dependencies of this architectural design -->
+
+- **Dependent Changes**:
+- **External System Dependencies**:
+- **Dependents**:
+
+---
+
+**Status**: 🟡 Draft

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

@@ -2,18 +2,100 @@
 name: /ss-create
 id: ss-create
 category: SuperSpec
-description: 创建变更 + 生成 proposal（boost 模式额外生成 spec + checklist）
+description: 创建变更 + 生成 proposal（boost 模式额外生成 spec + design(当你需要) + checklist）
 ---
 <!-- SUPERSPEC:START -->
+## 用户输入
+
+```text
+$ARGUMENTS
+```
+
+你**必须**在继续之前考虑用户输入（如果非空）。
+
+## 概述
+
+用户在 `/ss-create` 后输入的文本**就是**功能描述。除非用户提供了空命令，否则不要要求用户重复输入。
+
 **Guardrails**
-- 首先读取 `superspec.config.json` 获取 `lang`, `specDir`, `boost`, `strategy`, `context`
-- 检查 `{specDir}/changes/` 中现有变更，避免重复
-- 永远不要手动创建变更文件夹 —— 使用 `superspec create <name>` CLI
+- 首先读取 `superspec.config.json` → 获取 `lang`, `specDir`, `boost`, `strategy`, `context`, `branchPrefix`, `branchTemplate`, `changeNameTemplate`
+- **执行前置审查**（参考 AGENTS.md "Before ANY Task"）:
+  - 读取 `context` 文件、README、架构文档
+  - 查看 `{specDir}/changes/` → 通过 `depends_on` 避免重复变更
+- 永远不要手动创建变更文件夹 —— 使用 `superspec create <feature>` CLI
 - 在提案阶段不要编写任何代码，只创建设计文档
 
+**输入解析规则**
+
+从用户输入中提取四项：**功能名称**、**意图类型**、**开发者**、**语言**。
+
+| 提取项 | 规则 | 示例 |
+|--------|------|------|
+| 功能名称 | 转为 camelCase。中文 → 先翻译为英文 | "add user auth" → `addUserAuth`; "添加用户认证" → `addUserAuth` |
+| 意图类型 | 语义推断 | add/new/implement/新增/添加 → `feature`; fix/bug/hotfix/修复 → `hotfix`; refactor/optimize/重构 → `refactor`; docs → `docs`; test → `test`; build/deps → `chore`; 默认 → `feature` |
+| 开发者 | "@username" 或 "Developer: xxx" → 提取（移除"@"）。回退: git 用户名 | "添加todolist @jay" → user=`jay` |
+| 语言 | CJK 字符 → `zh`; 显式 "zh"/"中文" → `zh`; "en"/"English" → `en`; 回退: 配置 `lang` | "添加todolist" → `zh` |
+
+**命名模板**
+
+配置支持使用变量 `{date}`, `{feature}`, `{user}`, `{intentType}`, `{prefix}` 的自定义模板:
+- `branchTemplate`（默认: `{intentType}-{date}-{feature}-{user}`）
+- `changeNameTemplate`（默认: `{intentType}-{date}-{feature}-{user}`）
+
+```bash
+# "添加todolist @jay" → feature=addTodolist, user=jay, intentType=feature, lang=zh
+superspec create addTodolist --intent-type feature --lang zh
+# 分支: feature-20260212-addTodolist-jay
+
+# "fix login bug" → feature=fixLoginBug, intentType=hotfix, user=<git用户名>
+superspec create fixLoginBug --intent-type hotfix
+# 分支: hotfix-20260212-fixLoginBug-gitusername
+```
+
+如果用户提供自定义 `--branch-prefix`，添加到模板前面。
+
+**CLI 命令结构**
+```bash
+superspec create <feature> [options]
+  -b, --boost                          增强模式（spec + checklist）
+  -c, --creative                       创造模式（探索新方案）
+  -d, --description <desc>             变更描述
+  --no-branch                          跳过 git 分支创建
+  --spec-dir <dir>                     自定义 spec 文件夹
+  --branch-prefix <prefix>             自定义分支前缀
+  --branch-template <template>         覆盖分支名模板
+  --change-name-template <template>    覆盖文件夹名模板
+  --intent-type <type>                 意图类型（feature, hotfix, bugfix, refactor, chore）
+  --feature <feature>                  功能名称
+  --user <user>                        开发者标识
+  --lang <lang>                        SDD 文档语言（en, zh）
+```
+
+**何时使用 design.md**（boost 模式可选）:
+- 方案跨越多个系统或引入新架构模式
+- 重大架构决策且有显著权衡
+- 需要跨团队架构对齐
+
+**Spec 能力域拆分**（推荐用于大型变更）:
+当变更涉及多个独立能力时，按能力域拆分:
+```
+{specDir}/changes/<name>/
+├── proposal.md
+├── design.md      （可选）
+├── specs/
+│   ├── auth/spec.md
+│   ├── api/spec.md
+│   └── ui/spec.md
+├── tasks.md
+└── checklist.md
+```
+每个 spec.md < 300 行。在 proposal.md 中概述能力域，tasks.md 按能力域分组。
+
 **Steps**
-1. 运行 `superspec create <name> [-b] [-c] [-d <description>]` 创建变更结构
-2. 如果是 boost 模式 (-b)，额外生成 spec.md 和 checklist.md
-3. 读取生成的 proposal.md 理解变更范围
-4. 等待用户确认后再继续 /ss-tasks
+1. 解析用户输入 → 提取功能名（camelCase）、意图类型、开发者、语言
+2. 执行: `superspec create <feature> --intent-type <type> [--lang <lang>] [--user <user>]`
+3. 前置审查: 读取项目上下文、检查现有变更、理解依赖关系
+4. 评估复杂度: 如涉及多个独立能力域 → 考虑拆分 spec
+5. 读取生成的 proposal.md → 理解范围; 如需 design.md → 明确架构决策
+6. 等待用户确认后再继续 /ss-tasks
 <!-- SUPERSPEC:END -->

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

@@ -6,6 +6,7 @@ description: 添加 spec 依赖
 ---
 <!-- SUPERSPEC:START -->
 **Steps**
-1. 运行 `superspec link <name> --depends-on <other>`
+1. 运行 `superspec deps add <name> --on <other>`
 2. 这会更新 frontmatter: `depends_on: [other]`
+3. 验证: `superspec deps list <name>`
 <!-- SUPERSPEC:END -->

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

@@ -0,0 +1,54 @@
+---
+name: /ss-specs
+id: ss-specs
+category: SuperSpec
+description: 为大型变更创建多能力域 spec 结构
+---
+<!-- SUPERSPEC:START -->
+**用途**
+当 spec.md 因涉及多个独立能力域可能超过 300 行时，拆分为能力域维度的 spec 文件。
+
+**何时拆分**
+- 变更跨多个系统模块（如 auth + API + UI）
+- 单个 spec.md 预计超过 300 行
+- 需要并行开发多个独立能力
+
+**何时不拆分**
+- 单一模块变更或 spec.md < 200 行
+- 能力域之间高度耦合
+- 快速原型或实验性变更
+
+**能力域类型**
+`auth`（认证/授权）· `api`（REST/GraphQL）· `ui`（前端）· `data`（模型/schema）· `workflow`（业务流程）· `integration`（外部集成）· `infra`（部署）
+
+**Spec 模板**
+```markdown
+---
+name: <name>-<capability>
+status: draft
+strategy: {{strategy}}
+depends_on: []
+capability: <capability-name>
+---
+# Spec: <name> - <Capability>
+
+## 能力域范围
+## 用户故事
+### US-<capability>-1: [标题]
+## 功能需求
+### FR-<capability>-1: [标题]
+## 跨能力域依赖
+- 依赖 `auth/spec.md` 的 FR-auth-2
+- 为 `ui/spec.md` 提供 API-1
+## 边界情况
+```
+
+**ID 约定**: `US-<cap>-<n>`, `FR-<cap>-<n>`, `AC-<cap>-<n>.<sub>`
+
+**Steps**
+1. 在 proposal.md 中识别 2-5 个独立能力域
+2. 为每个能力域创建 `specs/<capability>/spec.md`，使用上述模板
+3. 在 design.md 中说明拆分理由
+4. 在 tasks.md 中按能力域分组任务
+5. 验证：边界清晰、依赖明确、每个 spec < 300 行、ID 遵循约定
+<!-- SUPERSPEC:END -->

package/templates/zh/design.md

@@ -0,0 +1,126 @@
+---
+name: {{name}}
+status: draft
+strategy: {{strategy}}
+depends_on: []
+---
+
+# 架构设计: {{name}}
+
+> 创建日期: {{date}}
+
+## 设计目标
+
+<!-- 描述本次架构设计要达成的核心目标 -->
+
+## 系统范围
+
+<!-- 说明本次变更涉及的系统/模块边界 -->
+
+- **影响的系统**:
+- **影响的模块**:
+- **不涉及的范围**:
+
+## 架构决策
+
+### 决策 1: [决策标题]
+
+**上下文**: 为什么需要这个决策?
+
+**可选方案**:
+- **方案 A**: [描述]
+  - 优点:
+  - 缺点:
+- **方案 B**: [描述]
+  - 优点:
+  - 缺点:
+
+**最终选择**: [选择的方案]
+
+**理由**: [为什么选择这个方案]
+
+### 决策 2: [决策标题]
+
+**上下文**:
+
+**可选方案**:
+- **方案 A**:
+- **方案 B**:
+
+**最终选择**:
+
+**理由**:
+
+## 架构图
+
+<!-- 使用 mermaid 或文本描述关键架构 -->
+
+```mermaid
+graph TD
+    A[组件A] --> B[组件B]
+    B --> C[组件C]
+```
+
+## 数据流
+
+<!-- 描述关键数据流转路径 -->
+
+1. 用户请求 →
+2. 处理层 →
+3. 存储层 →
+4. 响应
+
+## 技术栈选型
+
+<!-- 如引入新技术栈,说明选择理由 -->
+
+| 技术 | 版本 | 用途 | 选择理由 |
+|------|------|------|---------|
+| |  |  |  |
+
+## 性能影响
+
+- **预期性能变化**:
+- **潜在瓶颈**:
+- **优化策略**:
+
+## 安全考量
+
+- **身份认证**:
+- **权限控制**:
+- **数据加密**:
+- **审计日志**:
+
+## 扩展性考虑
+
+- **水平扩展能力**:
+- **垂直扩展能力**:
+- **未来演进路径**:
+
+## 迁移策略
+
+<!-- 如涉及重大架构变更,描述迁移步骤 -->
+
+1. **阶段 1**:
+2. **阶段 2**:
+3. **阶段 3**:
+
+**回滚方案**:
+
+## 风险与缓解
+
+| 风险 | 影响 | 概率 | 缓解措施 |
+|------|------|------|---------|
+| | | | |
+
+## 依赖关系
+
+<!-- 本架构设计依赖的其他变更或系统 -->
+
+- **依赖的变更**:
+- **依赖的外部系统**:
+- **被依赖方**:
+
+---
+
+**状态**: 🟡 草稿