@superspec/cli 1.1.1 → 1.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jay Hsueh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,374 @@
+<div align="center">
+
+# SuperSpec
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@superspec/cli"><img src="https://img.shields.io/npm/v/@superspec/cli.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@superspec/cli"><img src="https://img.shields.io/npm/dm/@superspec/cli.svg" alt="npm downloads"></a>
+  <a href="https://github.com/asasugar/SuperSpec/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="license"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg" alt="node version"></a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/asasugar/SuperSpec/master/assets/logo.svg" alt="SuperSpec" width="320" />
+</p>
+
+Spec-driven development (SDD) for AI-powered coding assistants.
+
+[Online Docs](https://asasugar.github.io/SuperSpec/) · [GitHub](https://github.com/asasugar/SuperSpec) · [中文文档](https://github.com/asasugar/SuperSpec/blob/master/README-zh.md)
+
+</div>
+
+## Why SuperSpec?
+
+AI coding assistants are powerful but often produce inconsistent, undocumented code when requirements are vague.
+
+**Supported AI assistants:** [Cursor](https://cursor.com), [Claude Code](https://claude.ai), [Qwen](https://tongyi.aliyun.com) (通义), [OpenCode](https://opencode.com), [Codex](https://codex.ai), [CodeBuddy](https://codebuddy.ai), [Qoder](https://qoder.com). Any editor that reads `AGENTS.md` can use the workflow. Use `superspec init --ai cursor|claude|qwen|opencode|codex|codebuddy|qoder` to install editor-specific rules and slash commands (default: `cursor`).
+
+### OpenSpec Pain Points
+
+| # | OpenSpec Pain Point | SuperSpec Solution |
+|---|---|---|
+| 1 | No spec size control — specs grow unbounded, eating AI context window | First Principles + `lint` (target 300 / hard 400 lines), auto-split via `/ss-specs` |
+| 2 | Validation inconsistency — `validate --strict` passes but `archive` fails | Unified validation pipeline: `lint` → `validate` → `checklist` → `archive` |
+| 3 | No implementation↔spec verification — spec drift after coding | `sync` collects git diff into `context.md`, `/ss-resume` cross-references with spec |
+| 4 | No context restoration workflow — context lost when switching AI conversations | `sync` + `context.md` + `/ss-resume` restores full spec context in new sessions |
+| 5 | No dependency management between specs | `depends_on` frontmatter + `deps add`/`deps list`/`deps remove` |
+| 6 | No search across specs and archived changes | `search` with `--archived`, `--artifact`, `--regex` filters |
+| 7 | No progress tracking or status visibility | `status` shows all changes with per-artifact status (Draft → Ready → Done) |
+| 8 | Single mode — same overhead for simple fixes and large features | Standard mode (lightweight) vs Boost mode (full US/FR/AC + checklist) |
+| 9 | No project-level configuration for AI context rules | `superspec.config.json` with `strategy`, `context`, `limits`, `branchTemplate` etc. |
+| 10 | No cross-reference validation (US↔FR↔AC↔tasks) | `validate --check-deps` ensures full traceability |
+| 11 | No i18n — English only | `--lang zh\|en`, full Chinese templates + CLI prompts |
+| 12 | No task granularity control | Boost mode: each task < 1 hour, phased with parallel markers `[P]` |
+| 13 | No automatic branch creation — inconsistent naming for change branches | `superspec create` auto-creates git branches from `branchTemplate`, with customizable `branchPrefix` / `branchTemplate` / `changeNameTemplate` |
+
+### Spec-Kit Pain Points
+
+| # | Spec-Kit Pain Point | SuperSpec Solution |
+|---|---|---|
+| 1 | Commands consume a large number of tokens, severely eating into the context window | Slash commands are file-based templates, loaded on-demand (zero idle cost) |
+| 2 | Creates "illusion of work" — generates excessive documentation | First Principles: every sentence must inform a decision, signal-over-noise |
+| 3 | Can't update/refine existing specs — always creates new branches | In-place spec evolution: edit proposal/spec/tasks directly, `/ss-clarify` for iterations |
+| 4 | Ignores existing project structure and conventions | `strategy: follow` reads `context` files as constraints, matches existing patterns |
+| 5 | Generates hundreds of unhelpful tests | No auto-test generation — task verification is developer-controlled |
+| 6 | Poor for incremental development / small tasks | Standard mode for quick features; Boost only when needed (`-b`) |
+| 7 | Python-based install (`uv tool`) — mismatched with JS/TS ecosystem | npm/pnpm/yarn install, native to Node.js ecosystem |
+| 8 | No spec dependency management between changes | `depends_on` + `deps add`/`deps list` with dependency graph |
+| 9 | No context restoration workflow | `sync` → `context.md` → `/ss-resume` for seamless continuation |
+| 10 | Fails when initialized in subfolders | Works anywhere — `superspec.config.json` at project root, `specDir` configurable |
+| 11 | No spec archiving with context preservation | `archive` moves completed changes, `search --archived` still finds them |
+| 12 | Incompatible with latest AI tool upgrades | Editor-agnostic `AGENTS.md` + per-editor rules via `--ai` flag |
+| 13 | Single mode and rigid configuration — no flexible switching between lightweight and Boost modes | SuperSpec lets you freely switch between Standard and Boost modes, with highly customizable `boost`, `strategy`, `branchTemplate` and more in `superspec.config.json` |
+| 14 | No creative/exploration mode | `strategy: create` (`-c`) allows proposing new architectures with documented trade-offs |
+
+## Installation
+
+```bash
+# npm
+npm install -g @superspec/cli
+
+# pnpm
+pnpm add -g @superspec/cli
+
+# yarn
+yarn global add @superspec/cli
+```
+
+> Requires Node.js >= 18.0.0
+
+## Quick Start
+
+```bash
+cd your-project
+
+superspec init                  # Default (English templates)
+superspec init --lang zh        # Chinese templates
+superspec init --ai claude      # Specify AI assistant type (cursor|claude|qwen|opencode|codex|codebuddy|qoder)
+superspec init --force          # Force overwrite existing config
+superspec init --no-git         # Skip git initialization
+```
+
+## Core Workflow
+
+```
+Standard:  create (proposal → checklist ✓) → tasks → apply → [vibe: sync → resume] → archive
+Boost:     create -b (proposal → spec → [auto: split? design?] → checklist ✓) → tasks → apply → ...
+```
+
+**Standard mode**: AI generates `proposal.md` (requirements + technical solution) → auto checklist (/10) → `tasks.md` — enough for simple features and bug fixes.
+
+**Boost mode**: AI generates `proposal.md` (requirements background) → `spec.md` (US/FR/AC details) → auto complexity assessment (split? design?) → auto checklist (/25) → `tasks.md` — for large features requiring design review and cross-validation.
+
+**Vibe coding phase**: after `apply`, use `sync` to collect git changes and `/ss-resume` to restore context in new AI conversations.
+
+## Slash Commands (AI Agent)
+
+These are the primary commands you use with AI assistants. Type them directly in your AI chat:
+
+### Main Flow
+
+| Command | Flags | What it does |
+|---------|-------|-------------|
+| `/ss-create <feature>` | `-b` boost, `-c` creative, `-d <desc>`, `--no-branch`, `--spec-dir <dir>`, `--branch-prefix <prefix>`, `--branch-template <tpl>`, `--change-name-template <tpl>`, `--intent-type <type>`, `--user <user>`, `--lang <lang>` | Create folder + branch, AI generates proposal (boost: + spec + design) with auto checklist gate |
+| `/ss-tasks` | — | Generate task list from proposal |
+| `/ss-apply` | — | Implement tasks one by one |
+| `/ss-resume` | — | Restore spec context for vibe coding (runs sync → reads context.md) |
+| `/ss-archive [name]` | `--all` | Archive completed change |
+
+### Quality & Discovery
+
+| Command | Mode | Flags | What it does |
+|---------|------|-------|-------------|
+| `/ss-clarify` | Both | — | Resolve ambiguity, record decisions |
+| `/ss-checklist` | Both | — | Quality gate: Standard (/10 after proposal) or Boost (/25 after spec). Auto-invoked by /ss-create |
+| `/ss-lint [name]` | Both | — | Check artifact sizes |
+| `/ss-validate [name]` | Boost | `--check-deps` | Cross-reference consistency check (US↔FR↔AC↔tasks) |
+| `/ss-status` | Both | — | View all changes and their status |
+| `/ss-search <q>` | Both | `--archived`, `--artifact <type>`, `--limit <n>`, `-E`/`--regex` | Full-text search across changes |
+| `/ss-link <name>` | Both | `--on <other>` | Add spec dependency |
+| `/ss-deps [name]` | Both | — | View dependency graph |
+
+### Usage Example
+
+```
+You:  /ss-create add user authentication @jay
+AI:   → runs `superspec create addUserAuth --intent-type feature`
+      → generates proposal.md (with requirements + technical solution)
+      → auto-runs checklist (/10) → pass
+      → prompts to run /ss-tasks
+
+You:  /ss-tasks
+AI:   → reads proposal.md → generates phased tasks
+
+You:  /ss-apply
+AI:   → implements tasks one by one, marks each ✅
+
+You:  /ss-resume    (new conversation / after a break)
+AI:   → runs sync → reads context.md → continues where you left off
+```
+
+## CLI Commands
+
+### Setup
+
+#### `superspec init`
+
+Initialize SuperSpec in current project.
+
+```bash
+superspec init                  # Default (English templates)
+superspec init --lang zh        # Chinese templates
+superspec init --ai claude      # Specify AI assistant type (cursor|claude|qwen|opencode|codex|codebuddy|qoder)
+superspec init --force          # Force overwrite existing config
+superspec init --no-git         # Skip git initialization
+```
+
+### Core Workflow
+
+#### `superspec create <feature>`
+
+Create a change folder and git branch. Artifacts are generated on demand by AI via `/ss-create`.
+
+```bash
+superspec create add-dark-mode                              # Standard mode
+superspec create add-auth -b                                # Boost mode (spec + design + checklist)
+superspec create redesign-ui -c                             # Creative mode (explore new patterns)
+superspec create new-arch -b -c --no-branch                 # Boost + creative + skip branch
+superspec create add-auth -d "OAuth2 integration"           # With description
+superspec create add-auth --spec-dir specs                  # Custom spec folder
+superspec create add-auth --branch-prefix feature/          # Custom branch prefix
+superspec create add-auth --branch-template "{prefix}{date}-{feature}-{user}"    # Custom branch name template
+superspec create add-auth --change-name-template "{date}-{feature}-{user}"       # Custom folder name template
+superspec create add-auth --intent-type hotfix              # Intent type (feature|hotfix|bugfix|refactor|chore)
+superspec create add-auth --user jay                        # Developer identifier
+superspec create add-auth --lang zh                         # SDD document language (en|zh)
+```
+
+#### `superspec archive [name]`
+
+Archive completed changes.
+
+```bash
+superspec archive add-auth      # Archive a specific change
+superspec archive --all         # Archive all completed changes
+```
+
+#### `superspec update`
+
+Refresh agent instructions and templates to latest version.
+
+```bash
+superspec update
+```
+
+### Quality & Validation
+
+#### `superspec lint [name]`
+
+Check artifact sizes against configured limits.
+
+```bash
+superspec lint add-auth         # Lint a specific change
+superspec lint                  # Lint all active changes
+```
+
+#### `superspec validate [name]`
+
+Cross-reference consistency check (US↔FR↔AC↔tasks).
+
+```bash
+superspec validate add-auth                 # Validate a specific change
+superspec validate add-auth --check-deps    # Validate with dependency check
+superspec validate                          # Validate all active changes
+```
+
+### Search & Discovery
+
+#### `superspec search <query>`
+
+Full-text search across all changes.
+
+```bash
+superspec search "JWT authentication"               # Search active changes
+superspec search "login flow" --archived             # Include archived changes
+superspec search "refresh token" --artifact tasks    # Filter by artifact type (proposal|spec|tasks|clarify|checklist)
+superspec search "auth" --limit 10                   # Limit results count (default: 50)
+superspec search "user\d+" -E                        # Use regex pattern matching
+```
+
+#### `superspec status`
+
+View all active changes and their artifact statuses.
+
+```bash
+superspec status
+```
+
+### Dependencies
+
+#### `superspec deps add <name>`
+
+```bash
+superspec deps add add-auth --on setup-database
+```
+
+#### `superspec deps remove <name>`
+
+```bash
+superspec deps remove add-auth --on setup-database
+```
+
+#### `superspec deps list [name]`
+
+```bash
+superspec deps list add-auth    # View deps for a specific change
+superspec deps list             # View all dependency relationships
+```
+
+### Vibe Coding (Post-SDD)
+
+#### `superspec sync [name]`
+
+Generate/refresh `context.md` summary with git diff (zero AI tokens — pure CLI).
+
+```bash
+superspec sync add-auth                 # Sync a specific change
+superspec sync add-auth --base develop  # Sync with custom base branch
+superspec sync add-auth --no-git        # Skip git diff collection
+superspec sync                          # Sync all active changes
+```
+
+## Strategy: follow vs create
+
+Each change has a `strategy` that controls how the AI agent approaches implementation:
+
+| | `follow` (default) | `create` (`-c`) |
+|---|---|---|
+| Reads project rules | Yes, as **constraints** | Yes, as **awareness** |
+| Architecture | Must align with existing | May propose alternatives |
+| File structure | Match existing patterns | May introduce new patterns |
+| Use case | Regular features, bug fixes | Refactoring, new modules, UX innovation |
+
+Configure project rule files in `superspec.config.json`:
+
+```json
+{
+  "context": [".cursor/rules/coding-style.mdc", "AGENTS.md", "docs/conventions.md"]
+}
+```
+
+## First Principles
+
+| # | Principle | Rule |
+|---|-----------|------|
+| I | Context Economy | < 300 lines per artifact, 400 hard limit |
+| II | Signal-to-Noise | Every sentence must inform a decision |
+| III | Intent Over Implementation | Focus on why and what, not how |
+| IV | Progressive Disclosure | Start minimal, expand only when needed |
+| V | Required Sections | Metadata, Problem, Solution, Success Criteria, Trade-offs |
+
+## Configuration
+
+`superspec init` generates `superspec.config.json`:
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `lang` | `"en"` | Template language (`zh` / `en`). Also controls CLI prompt language |
+| `specDir` | `"superspec"` | Spec folder name |
+| `branchPrefix` | `"spec/"` | Git branch prefix |
+| `boost` | `false` | Enable boost mode by default |
+| `strategy` | `"follow"` | `follow` = obey project rules, `create` = explore freely |
+| `context` | `[]` | Files AI should read for project conventions |
+| `limits.targetLines` | `300` | Target max lines per artifact |
+| `limits.hardLines` | `400` | Hard max lines per artifact |
+| `archive.dir` | `"archive"` | Archive subdirectory |
+| `archive.datePrefix` | `true` | Prefix archive folder with date |
+
+## Project Structure
+
+```
+SuperSpec/
+├── package.json                 # monorepo root
+├── pnpm-workspace.yaml
+├── tsconfig.json
+└── packages/
+    └── cli/                     # @superspec/cli
+        ├── package.json
+        ├── tsup.config.ts
+        ├── src/
+        │   ├── index.ts         # Library exports
+        │   ├── cli/             # CLI entry (commander)
+        │   ├── commands/        # create / archive / init / update / lint / validate / search / deps / status / sync
+        │   ├── core/            # config / template / frontmatter / lint / validate / context
+        │   ├── prompts/         # Agent rules installer
+        │   ├── ui/              # Terminal output (chalk)
+        │   └── utils/           # fs / git / date / paths / template
+        ├── templates/
+        │   ├── zh/              # Chinese templates
+        │   └── en/              # English templates
+        └── prompts/
+            ├── rules.md         # Rules.md template
+            └── agents.md        # AGENTS.md template
+```
+
+## Tech Stack
+
+- **Language**: TypeScript
+- **Build**: tsup
+- **Package Manager**: pnpm (monorepo)
+- **Runtime**: Node.js >= 18
+- **Dependencies**: commander, chalk
+
+## Development
+
+```bash
+pnpm install          # Install dependencies
+pnpm build            # Build all packages
+pnpm dev              # Watch mode
+pnpm --filter @superspec/cli typecheck   # Type check
+```
+
+## License
+
+MIT