superspec 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Hank Liu
+
+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,328 @@
+# SuperSpec
+
+> **Spec-Driven Development Framework**
+
+SuperSpec is a unified development framework that combines spec-driven documentation with TDD discipline.
+
+## Core Philosophy
+
+```
+Every Scenario becomes a test. Every test traces back to a Scenario.
+```
+
+| Principle | Description |
+|-----------|-------------|
+| **Specs First** | All development has Specs as the single source of truth |
+| **TDD Enforced** | Write tests first, watch them fail, then implement |
+| **Two-Phase Review** | Spec Compliance Review → Code Quality Review |
+| **Evidence First** | Verification over claims |
+| **Delta Tracking** | Structured change history |
+| **Archive Preservation** | Complete development documentation |
+
+## Unified Workflow
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  FULL WORKFLOW (large features, team review)                             │
+├─────────────────────────────────────────────────────────────────────────┤
+│  /superspec:brainstorm   →  Progressive design (Explore → Propose → Spec)│
+│          ↓                                                               │
+│  superspec validate      →  Validate specs (CLI) + team review           │
+│          ↓                                                               │
+│  /superspec:plan         →  Create TDD implementation plan               │
+└─────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────────────────────┐
+│  FAST TRACK (small-medium features)                                      │
+├─────────────────────────────────────────────────────────────────────────┤
+│  /superspec:kickoff      →  All-in-one: brainstorm + validate + plan     │
+└─────────────────────────────────────────────────────────────────────────┘
+
+          ↓ (both paths continue)
+
+/superspec:execute         Subagent-driven TDD implementation
+        ↓
+/superspec:verify          Verify implementation matches specs
+        ↓
+/superspec:finish-branch   Complete branch (merge/PR)
+        ↓
+/superspec:archive         Archive changes, apply Delta
+```
+
+### Four Phases of Brainstorming
+
+```
++----------------------------------------------------------+
+|              /superspec:brainstorm                        |
++----------------------------------------------------------+
+|                                                           |
+|   Phase 1: EXPLORE                                        |
+|   - Free exploration, understand the problem              |
+|   - Ask clarifying questions, visualize ideas             |
+|                                                           |
+|                    | Problem is clear                     |
+|                    v                                      |
+|                                                           |
+|   Phase 2: PROPOSE -> proposal.md                         |
+|   - Define Why (problem/opportunity)                      |
+|   - Define What Changes (change list)                     |
+|   - Define Capabilities (new/modified features)           |
+|   - Define Impact (affected areas)                        |
+|                                                           |
+|                    | Scope is defined                     |
+|                    v                                      |
+|                                                           |
+|   Phase 3: DESIGN -> design.md                            |
+|   - Compare 2-3 technical approaches                      |
+|   - Select recommended approach with rationale            |
+|   - Document trade-offs                                   |
+|                                                           |
+|                    | Approach is decided                  |
+|                    v                                      |
+|                                                           |
+|   Phase 4: SPEC -> specs/*.md                             |
+|   - Define Requirements (System SHALL...)                 |
+|   - Define Scenarios (WHEN/THEN -> each becomes a test)   |
+|                                                           |
++----------------------------------------------------------+
+```
+
+## Quick Start
+
+### Installation
+
+```bash
+# Install CLI
+npm install -g superspec
+
+# Or install from source
+git clone https://github.com/your-org/superspec
+cd superspec
+npm install
+npm run build
+npm link
+```
+
+### Claude Code Integration
+
+Skills are automatically installed to `~/.claude/skills/` when you run `superspec init`.
+
+### Initialize Project
+
+```bash
+superspec init
+```
+
+This will create:
+```
+your-project/
+└── superspec/
+    ├── project.yaml       # Project configuration
+    ├── specs/             # Specifications (source of truth)
+    └── changes/           # Change proposals
+```
+
+### Basic Usage
+
+```bash
+# FAST TRACK: Idea to plan in one session
+/superspec:kickoff
+
+# OR FULL WORKFLOW: Separate phases with review points
+# 1. Start a new change (four-phase brainstorming)
+/superspec:brainstorm
+
+# 2. Validate specifications (CLI command)
+superspec validate add-feature --strict
+
+# 3. Create implementation plan
+/superspec:plan
+
+# THEN CONTINUE (both paths):
+# 4. Execute plan (subagent-driven TDD)
+/superspec:execute
+
+# 5. Verify implementation (CLI command)
+superspec verify add-feature
+
+# 6. Complete branch (merge/PR/keep/discard)
+/superspec:finish-branch
+
+# 7. Archive changes (CLI command)
+superspec archive add-feature --yes
+```
+
+## Directory Structure
+
+### Project Structure
+
+```
+your-project/
+├── superspec/
+│   ├── specs/                    # Specifications (source of truth)
+│   │   └── [capability]/
+│   │       └── spec.md
+│   │
+│   └── changes/                  # Change proposals
+│       ├── [change-id]/          # In progress
+│       │   ├── proposal.md       # Why + What
+│       │   ├── design.md         # How (technical approach)
+│       │   ├── specs/            # Delta Specs
+│       │   ├── plan.md           # TDD implementation plan
+│       │   └── tasks.md          # Task list
+│       │
+│       └── archive/              # Completed
+│           └── YYYY-MM-DD-[id]/
+│
+└── src/                          # Actual code
+```
+
+### Spec Format
+
+```markdown
+# [Capability] Specification
+
+## Purpose
+[Feature purpose]
+
+## Requirements
+
+### Requirement: [Requirement Name]
+The system SHALL [behavior description]
+
+#### Scenario: [Scenario Name]
+- **WHEN** [trigger condition]
+- **THEN** [expected result]
+```
+
+### Spec-Test Mapping
+
+```
+Spec Scenario                     TDD Test
+===============================================================
+#### Scenario: Valid login    ->  test('Valid login', () => {
+- WHEN valid credentials            const result = login(valid);
+- THEN grants access                expect(result.granted).toBe(true);
+                                  });
+===============================================================
+```
+
+## CLI Commands
+
+```bash
+# Initialize
+superspec init [path]              # Initialize project
+
+# Query
+superspec list                     # List changes
+superspec list --specs             # List specifications
+superspec show [item]              # Show details
+
+# Validate
+superspec validate [id]            # Validate specification
+superspec validate [id] --strict   # Strict mode
+
+# Verify
+superspec verify [id]              # Verify implementation matches specs
+superspec verify [id] --strict     # Fail on extra code/tests
+superspec verify [id] --verbose    # Show detailed matching
+
+# Archive
+superspec archive [id]             # Archive change
+superspec archive [id] --yes       # Non-interactive mode
+```
+
+## Slash Commands (AI Assistant)
+
+| Command | Description |
+|---------|-------------|
+| `/superspec:kickoff` | **Fast track**: brainstorm + validate + plan in one session |
+| `/superspec:brainstorm` | **Full workflow**: Progressive design (Explore → Propose → Spec) |
+| `/superspec:plan` | Create TDD implementation plan (after brainstorm) |
+| `/superspec:execute` | Subagent-driven execution |
+| `/superspec:verify` | Verify implementation matches specs |
+| `/superspec:finish-branch` | Complete branch (merge/PR/keep/discard) |
+| `/superspec:archive` | Archive changes |
+
+## Skill System
+
+### Design Phase
+- `superspec:kickoff` - **Fast track**: idea to plan in one session
+- `superspec:brainstorm` - **Full workflow**: progressive design only
+
+### Planning Phase
+- `superspec:plan` - Create TDD plan (after brainstorm)
+- `git-worktree` - Git Worktree management
+
+### Implementation Phase
+- `tdd` - TDD cycle (with `testing-anti-patterns.md` reference)
+- `superspec:execute` - Subagent-driven development (default)
+- `executing-plans` - Batch execution with checkpoints (alternative)
+- `dispatching-parallel-agents` - For 2+ independent parallel tasks
+- `systematic-debugging` - Systematic debugging (with support files)
+
+### Quality & Discipline Phase
+- `verification-before-completion` - Evidence before completion claims
+- `receiving-code-review` - Handle code review feedback professionally
+
+### Review Phase
+- `spec-validation` - Specification validation
+- `code-review` - Code review (with `code-reviewer.md` template)
+
+### Completion Phase
+- `superspec:verify` - Verify implementation
+- `superspec:finish-branch` - Complete branch (merge/PR/keep/discard)
+- `superspec:archive` - Archive changes
+
+## Two-Phase Review
+
+```
++------------------------------------------+
+| Stage 1: Spec Compliance Review          |
+| - Read Spec files                        |
+| - Check each Requirement is implemented  |
+| - Check each Scenario has a test         |
+| - Check no extra/missing features        |
++------------------------------------------+
+                    |
+              [After passing]
+                    v
++------------------------------------------+
+| Stage 2: Code Quality Review             |
+| - Error handling                         |
+| - Type safety                            |
+| - SOLID principles                       |
+| - Test quality                           |
++------------------------------------------+
+```
+
+## Iron Rules
+
+### TDD Rule
+```
+No production code without a failing test first
+```
+
+### Spec Rule
+```
+Specs are the source of truth. Changes are proposals.
+```
+
+### SuperSpec Rule
+```
+Every Scenario becomes a test. Every test traces back to a Scenario.
+```
+
+### Verification Rule
+```
+No completion claims without fresh verification evidence
+```
+"It should work" is not evidence. Run the test. Show the output. Then claim completion.
+
+## License
+
+MIT License
+
+---
+
+**SuperSpec** - Spec-Driven + TDD Discipline = Traceable High-Quality Development

package/dist/cli/commands/archive.d.ts

@@ -0,0 +1,7 @@
+interface ArchiveOptions {
+    yes?: boolean;
+    skipSpecs?: boolean;
+}
+export declare function archiveCommand(id: string | undefined, options: ArchiveOptions): Promise<void>;
+export {};
+//# sourceMappingURL=archive.d.ts.map

package/dist/cli/commands/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/archive.ts"],"names":[],"mappings":"AAgBA,UAAU,cAAc;IACtB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAWD,wBAAsB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAuHnG"}

package/dist/cli/commands/archive.js

@@ -0,0 +1,322 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, copyFileSync, rmSync } from 'fs';
+import { join } from 'path';
+import { PALETTE, ICONS, commandHeader, sectionHeader, startSpinner, spinnerSuccess, spinnerFail, isInteractive, selectChange, confirmDangerous, displayCommand, } from '../ui/index.js';
+export async function archiveCommand(id, options) {
+    const superspecPath = join(process.cwd(), 'superspec');
+    if (!existsSync(superspecPath)) {
+        console.log(`  ${ICONS.error} ${PALETTE.error('SuperSpec not initialized.')}`);
+        console.log(`  ${PALETTE.dim('Run:')} ${PALETTE.accent('superspec init')}`);
+        process.exit(1);
+    }
+    // Interactive mode if no ID provided
+    if (!id) {
+        if (!isInteractive()) {
+            console.log(PALETTE.error('Please specify a change ID to archive.'));
+            process.exit(1);
+        }
+        const changesPath = join(superspecPath, 'changes');
+        const changes = [];
+        if (existsSync(changesPath)) {
+            const entries = readdirSync(changesPath, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory() && entry.name !== 'archive') {
+                    changes.push(entry.name);
+                }
+            }
+        }
+        if (changes.length === 0) {
+            console.log(`  ${ICONS.warning} ${PALETTE.warning('No active changes found.')}`);
+            return;
+        }
+        id = await selectChange(changes, 'Select a change to archive:');
+    }
+    const changePath = join(superspecPath, 'changes', id);
+    if (!existsSync(changePath)) {
+        console.log(`  ${ICONS.error} ${PALETTE.error(`Change not found: ${id}`)}`);
+        process.exit(1);
+    }
+    console.log(commandHeader(`archive ${id}`, 'Archive completed change'));
+    // Check prerequisites
+    const checkSpinner = startSpinner('Checking prerequisites...');
+    const checks = checkPrerequisites(changePath);
+    if (!checks.valid) {
+        spinnerFail(checkSpinner, 'Prerequisites not met');
+        console.log(sectionHeader('Issues Found', '❌'));
+        console.log();
+        for (const issue of checks.issues) {
+            console.log(`  ${ICONS.error} ${PALETTE.muted(issue)}`);
+        }
+        console.log();
+        process.exit(1);
+    }
+    spinnerSuccess(checkSpinner, 'All prerequisites met');
+    // Show what will happen
+    console.log(sectionHeader('Archive Actions', '📦'));
+    console.log();
+    const actions = [];
+    if (!options.skipSpecs) {
+        actions.push('Apply delta specs to main specifications');
+    }
+    actions.push(`Move ${id} to archive/`);
+    for (let i = 0; i < actions.length; i++) {
+        console.log(`  ${PALETTE.accent(`${i + 1}.`)} ${actions[i]}`);
+    }
+    console.log();
+    // Confirm
+    if (!options.yes) {
+        console.log(`  ${ICONS.warning} ${PALETTE.warning('This action will modify your main specifications.')}`);
+        console.log();
+        const confirmed = await confirmDangerous({
+            message: 'Proceed with archive?',
+        });
+        if (!confirmed) {
+            console.log();
+            console.log(`  ${PALETTE.dim('Archive cancelled.')}`);
+            return;
+        }
+    }
+    console.log();
+    try {
+        // Apply deltas
+        if (!options.skipSpecs) {
+            await applyDeltas(superspecPath, changePath);
+        }
+        // Move to archive
+        await moveToArchive(superspecPath, changePath, id);
+        console.log();
+        console.log(`  ${PALETTE.subtle('─'.repeat(50))}`);
+        console.log();
+        console.log(`  ${ICONS.success} ${PALETTE.bold(PALETTE.success('Archive complete!'))}`);
+        console.log(sectionHeader('Next Steps', '🚀'));
+        console.log();
+        displayCommand('superspec validate --all', 'Run validation');
+        console.log(`  ${PALETTE.dim('Verify main specs are updated correctly')}`);
+        console.log();
+    }
+    catch (err) {
+        console.log();
+        console.log(`  ${ICONS.error} ${PALETTE.bold(PALETTE.error('Archive failed'))}`);
+        console.log(`  ${PALETTE.muted(err instanceof Error ? err.message : String(err))}`);
+        process.exit(1);
+    }
+}
+function checkPrerequisites(changePath) {
+    const issues = [];
+    // Check required files
+    if (!existsSync(join(changePath, 'proposal.md'))) {
+        issues.push('Missing proposal.md');
+    }
+    if (!existsSync(join(changePath, 'design.md'))) {
+        issues.push('Missing design.md');
+    }
+    if (!existsSync(join(changePath, 'specs'))) {
+        issues.push('Missing specs/ directory');
+    }
+    // Check tasks completion (if tasks.md exists)
+    const tasksPath = join(changePath, 'tasks.md');
+    if (existsSync(tasksPath)) {
+        const content = readFileSync(tasksPath, 'utf-8');
+        const incomplete = (content.match(/^- \[ \]/gm) ?? []).length;
+        if (incomplete > 0) {
+            issues.push(`${incomplete} incomplete tasks in tasks.md`);
+        }
+    }
+    return { valid: issues.length === 0, issues };
+}
+async function applyDeltas(superspecPath, changePath) {
+    const specsPath = join(changePath, 'specs');
+    const mainSpecsPath = join(superspecPath, 'specs');
+    if (!existsSync(specsPath)) {
+        return;
+    }
+    const spinner = startSpinner('Applying delta specs...');
+    const entries = readdirSync(specsPath, { withFileTypes: true });
+    let appliedCount = 0;
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            const deltaSpecPath = join(specsPath, entry.name, 'spec.md');
+            if (existsSync(deltaSpecPath)) {
+                const content = readFileSync(deltaSpecPath, 'utf-8');
+                const operations = parseDeltaOperations(content);
+                if (operations.length > 0) {
+                    await applyDeltaToMainSpec(mainSpecsPath, entry.name, operations, content);
+                    appliedCount++;
+                }
+                else {
+                    // No delta markers - this is a new spec, copy as-is
+                    const targetDir = join(mainSpecsPath, entry.name);
+                    const targetPath = join(targetDir, 'spec.md');
+                    if (!existsSync(targetDir)) {
+                        mkdirSync(targetDir, { recursive: true });
+                    }
+                    copyFileSync(deltaSpecPath, targetPath);
+                    appliedCount++;
+                }
+            }
+        }
+    }
+    spinnerSuccess(spinner, `Applied ${appliedCount} specifications`);
+}
+function parseDeltaOperations(content) {
+    const operations = [];
+    const lines = content.split('\n');
+    let currentSection = null;
+    let currentReq = '';
+    let currentContent = [];
+    for (const line of lines) {
+        // Detect section headers
+        if (line.match(/^## ADDED Requirements/i)) {
+            currentSection = 'added';
+            continue;
+        }
+        if (line.match(/^## MODIFIED Requirements/i)) {
+            currentSection = 'modified';
+            continue;
+        }
+        if (line.match(/^## REMOVED Requirements/i)) {
+            currentSection = 'removed';
+            continue;
+        }
+        if (line.match(/^## RENAMED Requirements/i)) {
+            currentSection = 'renamed';
+            continue;
+        }
+        // Detect new requirement
+        const reqMatch = line.match(/^### Requirement: (.+)$/);
+        if (reqMatch?.[1] && currentSection) {
+            // Save previous if exists
+            if (currentReq) {
+                operations.push({
+                    type: currentSection,
+                    requirement: currentReq,
+                    content: currentContent.join('\n'),
+                });
+            }
+            currentReq = reqMatch[1];
+            currentContent = [line];
+            continue;
+        }
+        // Detect renamed format
+        if (currentSection === 'renamed') {
+            const fromMatch = line.match(/^- FROM:.*`### Requirement: (.+)`/);
+            const toMatch = line.match(/^- TO:.*`### Requirement: (.+)`/);
+            if (fromMatch?.[1]) {
+                currentReq = fromMatch[1];
+            }
+            if (toMatch?.[1] && currentReq) {
+                operations.push({
+                    type: 'renamed',
+                    requirement: currentReq,
+                    fromName: currentReq,
+                    toName: toMatch[1],
+                });
+                currentReq = '';
+            }
+            continue;
+        }
+        // Collect content
+        if (currentReq && currentSection) {
+            currentContent.push(line);
+        }
+    }
+    // Don't forget last one
+    if (currentReq && currentSection) {
+        operations.push({
+            type: currentSection,
+            requirement: currentReq,
+            content: currentContent.join('\n'),
+        });
+    }
+    return operations;
+}
+async function applyDeltaToMainSpec(mainSpecsPath, capability, operations, fullContent) {
+    const mainSpecDir = join(mainSpecsPath, capability);
+    const mainSpecPath = join(mainSpecDir, 'spec.md');
+    // Create directory if needed
+    if (!existsSync(mainSpecDir)) {
+        mkdirSync(mainSpecDir, { recursive: true });
+    }
+    let mainContent = '';
+    if (existsSync(mainSpecPath)) {
+        mainContent = readFileSync(mainSpecPath, 'utf-8');
+    }
+    // Sort operations: RENAMED → REMOVED → MODIFIED → ADDED
+    const sorted = [...operations].sort((a, b) => {
+        const order = { renamed: 0, removed: 1, modified: 2, added: 3 };
+        return order[a.type] - order[b.type];
+    });
+    for (const op of sorted) {
+        switch (op.type) {
+            case 'renamed':
+                if (op.fromName && op.toName) {
+                    mainContent = mainContent.replace(`### Requirement: ${op.fromName}`, `### Requirement: ${op.toName}`);
+                    console.log(`  ${PALETTE.cyan('→')} Renamed: ${op.fromName} → ${op.toName}`);
+                }
+                break;
+            case 'removed':
+                // Remove the requirement section
+                const removePattern = new RegExp(`### Requirement: ${escapeRegex(op.requirement)}[\\s\\S]*?(?=### Requirement:|$)`, 'g');
+                mainContent = mainContent.replace(removePattern, '');
+                console.log(`  ${PALETTE.error('−')} Removed: ${op.requirement}`);
+                break;
+            case 'modified':
+                // Replace existing requirement
+                if (op.content) {
+                    const modifyPattern = new RegExp(`### Requirement: ${escapeRegex(op.requirement)}[\\s\\S]*?(?=### Requirement:|$)`, 'g');
+                    mainContent = mainContent.replace(modifyPattern, op.content.trim() + '\n\n');
+                    console.log(`  ${PALETTE.warning('~')} Modified: ${op.requirement}`);
+                }
+                break;
+            case 'added':
+                // Append to end of requirements section
+                if (op.content) {
+                    mainContent = mainContent.trimEnd() + '\n\n' + op.content.trim() + '\n';
+                    console.log(`  ${PALETTE.success('+')} Added: ${op.requirement}`);
+                }
+                break;
+        }
+    }
+    // Write updated spec
+    writeFileSync(mainSpecPath, mainContent.trim() + '\n');
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+async function moveToArchive(superspecPath, changePath, id) {
+    const date = new Date().toISOString().split('T')[0];
+    const archiveId = `${date}-${id}`;
+    const archivePath = join(superspecPath, 'changes', 'archive', archiveId);
+    const spinner = startSpinner(`Moving to archive/${archiveId}...`);
+    // Create archive directory
+    mkdirSync(archivePath, { recursive: true });
+    // Move all files
+    const entries = readdirSync(changePath, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = join(changePath, entry.name);
+        const destPath = join(archivePath, entry.name);
+        if (entry.isDirectory()) {
+            copyDirSync(srcPath, destPath);
+        }
+        else {
+            copyFileSync(srcPath, destPath);
+        }
+    }
+    // Remove original
+    rmSync(changePath, { recursive: true });
+    spinnerSuccess(spinner, `Archived to ${archiveId}`);
+}
+function copyDirSync(src, dest) {
+    mkdirSync(dest, { recursive: true });
+    const entries = readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = join(src, entry.name);
+        const destPath = join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDirSync(srcPath, destPath);
+        }
+        else {
+            copyFileSync(srcPath, destPath);
+        }
+    }
+}
+//# sourceMappingURL=archive.js.map