superspec 0.1.0

package/dist/index.js

@@ -0,0 +1,44 @@
+/**
+ * SuperSpec - Unified Spec-Driven Development Framework
+ *
+ * Core Principle:
+ * Every Scenario becomes a test, every test traces to a Scenario.
+ *
+ * @module superspec
+ */
+// Core exports
+export { validateSpec, validateSpecSet } from './core/validation/spec-validator.js';
+export { parseSpec, parseDeltaSpec, serializeSpec } from './core/parsers/spec-parser.js';
+export { loadProjectConfig, getDefaultConfig, serializeConfig } from './core/config/project-config.js';
+/**
+ * SuperSpec version
+ */
+export const VERSION = '0.1.0';
+/**
+ * Core principles (Iron Laws)
+ */
+export const IRON_LAWS = {
+    TDD: 'NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST',
+    SPECS: 'SPECS ARE TRUTH. CHANGES ARE PROPOSALS.',
+    SUPERSPEC: 'EVERY SCENARIO BECOMES A TEST. EVERY TEST TRACES TO A SCENARIO.',
+};
+/**
+ * Workflow phases
+ */
+export const WORKFLOW_PHASES = [
+    'brainstorm',
+    'plan',
+    'execute',
+    'verify',
+    'archive',
+];
+/**
+ * Brainstorm sub-phases
+ */
+export const BRAINSTORM_PHASES = [
+    'explore',
+    'propose',
+    'design',
+    'spec',
+];
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,eAAe;AACf,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAGpF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAGzF,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAGvG;;GAEG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAE/B;;GAEG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,GAAG,EAAE,iDAAiD;IACtD,KAAK,EAAE,yCAAyC;IAChD,SAAS,EAAE,iEAAiE;CACpE,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,YAAY;IACZ,MAAM;IACN,SAAS;IACT,QAAQ;IACR,SAAS;CACD,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,SAAS;IACT,SAAS;IACT,QAAQ;IACR,MAAM;CACE,CAAC"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "superspec",
+  "version": "0.1.0",
+  "description": "SuperSpec - Unified spec-driven development framework",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "superspec": "dist/cli/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "test:coverage": "vitest --coverage",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist/",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "superspec",
+    "tdd",
+    "specification",
+    "development",
+    "workflow",
+    "testing",
+    "bdd",
+    "documentation"
+  ],
+  "author": "Hank Liu",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HankLiu447/superspec.git"
+  },
+  "bugs": {
+    "url": "https://github.com/HankLiu447/superspec/issues"
+  },
+  "homepage": "https://github.com/HankLiu447/superspec#readme",
+  "dependencies": {
+    "@inquirer/prompts": "^8.2.0",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "glob": "^10.3.10",
+    "gray-matter": "^4.0.3",
+    "ora": "^9.0.0",
+    "yaml": "^2.3.4",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@typescript-eslint/eslint-plugin": "^6.19.0",
+    "@typescript-eslint/parser": "^6.19.0",
+    "eslint": "^8.56.0",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist/",
+    "templates/",
+    "schemas/"
+  ]
+}

package/schemas/superspec-workflow/schema.yaml

@@ -0,0 +1,166 @@
+name: superspec-workflow
+version: 2
+description: |
+  SuperSpec unified spec-driven development workflow.
+
+  Flow: brainstorm → plan → execute → verify → archive
+
+  Brainstorm is a progressive flow: Explore → Propose → Design → Spec
+
+artifacts:
+  # ============================================
+  # Phase 1: Brainstorm (Explore → Propose → Design → Spec)
+  # ============================================
+  - id: brainstorm
+    generates:
+      - proposal.md
+      - design.md
+      - "specs/**/*.md"
+    description: |
+      Progressive design flow from exploration to specifications.
+      Four phases: Explore → Propose → Design → Spec
+    instruction: |
+      Use the brainstorm skill for a progressive flow:
+
+      **Phase 1: EXPLORE**
+      - Free-form exploration
+      - Ask clarifying questions (one at a time)
+      - Investigate codebase
+      - Visualize with ASCII diagrams
+      - Challenge assumptions
+
+      Transition: "Problem is clear enough, let's define the change scope"
+
+      **Phase 2: PROPOSE**
+      - Define Why (problem/opportunity)
+      - Define What Changes
+      - Define Capabilities (new/modified)
+      - Define Impact
+      - Generate proposal.md
+
+      Transition: "Change scope is defined, let's design the technical approach"
+
+      **Phase 3: DESIGN**
+      - Present 2-3 approaches with trade-offs
+      - Compare and recommend
+      - Document technical decisions
+      - Generate design.md
+
+      Transition: "Technical approach is decided, let's define the specifications"
+
+      **Phase 4: SPEC**
+      - Define Requirements (system SHALL...)
+      - Define Scenarios (WHEN/THEN) - each becomes a test
+      - Generate specs/*.md
+
+      Output:
+      - superspec/changes/[id]/proposal.md
+      - superspec/changes/[id]/design.md
+      - superspec/changes/[id]/specs/[capability]/spec.md
+    requires: []
+
+  # ============================================
+  # Phase 2: Planning
+  # ============================================
+  - id: plan
+    generates: plan.md
+    description: TDD implementation plan based on Specs
+    template: plan.md
+    instruction: |
+      Create TDD implementation plan. Each Scenario becomes a test.
+
+      Structure for each task:
+      - **Spec Reference**: Link to Requirement and Scenario
+      - **Files**: Create/Modify/Test paths
+      - **Step 1**: Write failing test (RED) - based on Scenario
+      - **Step 2**: Run to verify failure
+      - **Step 3**: Implement minimal code (GREEN)
+      - **Step 4**: Run to verify pass
+      - **Step 5**: Refactor (if needed)
+      - **Step 6**: Commit with Spec reference
+
+      Scenario → Test mapping:
+      ```
+      #### Scenario: Valid login       →  test('Valid login', () => {
+      - WHEN valid credentials              // WHEN
+      - THEN grants access                  expect(login(valid).granted).toBe(true);
+                                          });
+      ```
+    requires:
+      - brainstorm
+
+  - id: tasks
+    generates: tasks.md
+    description: Implementation task checklist
+    template: tasks.md
+    instruction: |
+      Create task checklist from plan.md.
+
+      Format:
+      - [ ] X.Y Write test for Scenario: [name]
+        - Spec: Requirement X → Scenario Y
+      - [ ] X.Z Implement [feature]
+      - [ ] X.W Commit
+
+      Each task: 2-5 minutes, verifiable, references Spec.
+    requires:
+      - plan
+
+# ============================================
+# Apply Phase: TDD Implementation
+# ============================================
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  instruction: |
+    Execute plan using TDD and subagent-driven development.
+
+    **Per Task Flow:**
+    1. Dispatch Implementer subagent
+       - TDD: Write test (RED) → Implement (GREEN) → Refactor
+       - Self-review
+
+    2. Dispatch Spec Reviewer subagent
+       - Verify: Implementation matches Requirement + Scenarios
+       - Check: No missing features, no extra features
+
+    3. Dispatch Quality Reviewer (after spec passes)
+       - Check: Error handling, type safety, SOLID
+       - Classify: Critical / Important / Suggestion
+
+    4. Mark task complete
+
+    After all tasks: Final code review.
+
+# ============================================
+# Verify Phase
+# ============================================
+verify:
+  requires: [apply]
+  instruction: |
+    Verify implementation matches specifications.
+
+    Checks:
+    1. Every Requirement has implementation
+    2. Every Scenario has test
+    3. All tests pass
+    4. No features outside Specs
+
+    Run: `superspec validate [change-id] --strict`
+
+# ============================================
+# Archive Phase
+# ============================================
+archive:
+  requires: [verify]
+  instruction: |
+    Archive change and apply deltas to main specs.
+
+    Steps:
+    1. Verify all tests pass
+    2. Apply Deltas to superspec/specs/
+    3. Move to superspec/changes/archive/YYYY-MM-DD-[id]/
+    4. Finish branch (merge/PR/keep/discard)
+    5. Clean up worktree
+
+    Run: `superspec archive [change-id] --yes`

package/templates/design.md

@@ -0,0 +1,71 @@
+# Design: [Feature Name]
+
+## Context
+[Background, current state, constraints]
+
+## Goals / Non-Goals
+
+### Goals
+- [What this design achieves]
+
+### Non-Goals
+- [What this design explicitly excludes]
+
+## Approaches Considered
+
+### Approach A: [Name]
+[Description]
+
+**Pros:**
+- [Advantage 1]
+- [Advantage 2]
+
+**Cons:**
+- [Disadvantage 1]
+- [Disadvantage 2]
+
+### Approach B: [Name]
+[Description]
+
+**Pros:**
+- [Advantages]
+
+**Cons:**
+- [Disadvantages]
+
+### Approach C: [Name] (if applicable)
+[Description]
+
+## Decision
+
+**Chosen Approach:** [A/B/C]
+
+**Rationale:**
+[Why this approach was selected]
+
+## Trade-offs
+[What we're giving up and why it's acceptable]
+
+## Technical Details
+
+### Architecture
+[High-level architecture description]
+
+### Key Components
+- [Component 1]: [Purpose]
+- [Component 2]: [Purpose]
+
+### Data Flow
+```
+[ASCII diagram of data flow]
+```
+
+## Risks and Mitigations
+| Risk | Mitigation |
+|------|------------|
+| [Risk 1] | [How to mitigate] |
+| [Risk 2] | [How to mitigate] |
+
+## Open Questions
+- [Question 1]
+- [Question 2]

package/templates/plan.md

@@ -0,0 +1,78 @@
+# [Feature] Implementation Plan
+
+> **For Claude:** REQUIRED SKILL: Use superspec:execute to implement this plan.
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+**Related Documents:**
+- Design: `superspec/changes/[id]/design.md`
+- Specs: `superspec/changes/[id]/specs/[capability]/spec.md`
+
+---
+
+## Task 1: [Component/Feature Name]
+
+**Spec Reference:** `### Requirement: [Name]`
+
+**Files:**
+- Create: `exact/path/to/new-file.ts`
+- Modify: `exact/path/to/existing.ts:123-145`
+- Test: `tests/exact/path/to/test.ts`
+
+### Step 1.1: Write failing test (RED)
+
+**Scenario:** `#### Scenario: [Name]`
+
+```typescript
+// WHEN [condition from Scenario]
+// THEN [result from Scenario]
+test('[Scenario Name]', async () => {
+  // WHEN
+  const result = await action(input);
+
+  // THEN
+  expect(result).toEqual(expected);
+});
+```
+
+**Run:** `npm test -- --grep "[Scenario Name]"`
+**Expected:** FAIL - "[function] is not defined"
+
+### Step 1.2: Implement minimal code (GREEN)
+
+```typescript
+export async function action(input: Input): Promise<Output> {
+  // Minimal implementation to pass test
+  return expected;
+}
+```
+
+**Run:** `npm test -- --grep "[Scenario Name]"`
+**Expected:** PASS
+
+### Step 1.3: Refactor (if needed)
+
+[Clean up code while keeping tests green]
+
+### Step 1.4: Commit
+
+```bash
+git add tests/path/test.ts src/path/file.ts
+git commit -m "feat([capability]): implement [scenario]
+
+Refs: superspec/changes/[id]/specs/[capability]/spec.md
+Requirement: [Name]
+Scenario: [Name]"
+```
+
+---
+
+## Task 2: [Next Component]
+
+**Spec Reference:** `### Requirement: [Name]`
+
+[Repeat structure...]

package/templates/proposal.md

@@ -0,0 +1,36 @@
+# Change: [Brief Description]
+
+## Why
+[1-2 sentences on problem/opportunity]
+
+What problem does this solve?
+Why is this the right time to address it?
+
+## What Changes
+- [Change item 1]
+- [Change item 2]
+- [**BREAKING**: Mark breaking changes]
+
+## Capabilities
+
+### New Capabilities
+<!-- List new specs to create - each becomes superspec/changes/[id]/specs/[name]/spec.md -->
+- [capability-1]: [brief description]
+
+### Modified Capabilities
+<!-- List existing specs that will change - check superspec/specs/ first -->
+- [existing-capability]: [what changes]
+
+## Impact
+- Affected specs: [list]
+- Affected code: [key files/systems]
+- Affected APIs: [endpoints]
+- Dependencies: [new/changed dependencies]
+
+<!--
+NOTE: Design Considerations (approaches, trade-offs, technical decisions)
+should be documented in design.md, NOT in this file.
+
+This file focuses on WHY and WHAT.
+design.md focuses on HOW.
+-->

package/templates/spec.md

@@ -0,0 +1,57 @@
+# [Capability Name] Specification
+
+## Purpose
+[1-2 sentences explaining what this capability provides]
+
+## Requirements
+
+### Requirement: [Requirement Name]
+The system SHALL [behavior description].
+
+#### Scenario: [Scenario Name]
+- **WHEN** [trigger condition]
+- **THEN** [expected result]
+- **AND** [additional result] (optional)
+
+#### Scenario: [Another Scenario]
+- **WHEN** [different condition]
+- **THEN** [different result]
+
+### Requirement: [Another Requirement]
+The system SHALL [another behavior].
+
+#### Scenario: [Scenario Name]
+- **WHEN** [condition]
+- **THEN** [result]
+
+<!--
+Delta Spec Format (for changes to existing specs):
+
+## ADDED Requirements
+
+### Requirement: [New Feature]
+The system SHALL [new behavior].
+
+#### Scenario: [New Scenario]
+- **WHEN** [condition]
+- **THEN** [result]
+
+## MODIFIED Requirements
+
+### Requirement: [Existing Feature Name - MUST MATCH EXACTLY]
+The system SHALL [updated behavior - FULL CONTENT REQUIRED].
+
+#### Scenario: [Updated Scenario]
+- **WHEN** [updated condition]
+- **THEN** [updated result]
+
+## REMOVED Requirements
+
+### Requirement: [Deprecated Feature]
+**Reason**: [Why removing]
+**Migration**: [How to handle existing usage]
+
+## RENAMED Requirements
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+-->

package/templates/tasks.md

@@ -0,0 +1,29 @@
+# Implementation Tasks for [Change ID]
+
+## Status
+- Total Tasks: X
+- Completed: 0
+- In Progress: 0
+- Pending: X
+
+---
+
+## 1. [Phase/Component Name]
+
+- [ ] 1.1 Write test for Scenario: [name]
+  - Spec: `### Requirement: X` → `#### Scenario: Y`
+- [ ] 1.2 Implement [function/component]
+- [ ] 1.3 Commit: feat([cap]): [description]
+
+## 2. [Next Phase]
+
+- [ ] 2.1 Write test for Scenario: [name]
+  - Spec: `### Requirement: X` → `#### Scenario: Y`
+- [ ] 2.2 Implement [function/component]
+- [ ] 2.3 Commit
+
+## 3. [Final Phase]
+
+- [ ] 3.1 Integration tests
+- [ ] 3.2 Final review
+- [ ] 3.3 Documentation updates