@panuwatbas/spec-driven-dev 1.0.2

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@panuwatbas/spec-driven-dev",
+  "version": "1.0.2",
+  "description": "Spec-Driven Development skill inspired by Kiro IDE. Plan first, then build. Requirements -> Design -> Tasks workflow for AI agents.",
+  "keywords": [
+    "spec-driven-development",
+    "kiro",
+    "ai-skill",
+    "requirements",
+    "design",
+    "tasks",
+    "gemini",
+    "cursor",
+    "windsurf",
+    "copilot",
+    "ai-agent",
+    "planning",
+    "spec"
+  ],
+  "author": "",
+  "license": "MIT",
+  "bin": {
+    "spec-driven-dev": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "skill/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "homepage": "",
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/skill/README.md

@@ -0,0 +1,346 @@
+# Spec-Driven Development Skill
+
+> **Plan first, then build.** สร้าง Requirements → Design → Tasks ก่อน แล้วค่อย Code
+
+Skill นี้เลียนแบบ workflow ของ **Kiro IDE** ที่เน้นการวางแผนอย่างเป็นระบบ
+ก่อนเขียน code ทุกครั้ง ลดความผิดพลาด ลดการทำซ้ำ และสร้าง documentation ที่มีชีวิต
+
+---
+
+## Features
+
+- **Structured Planning** — 3 เฟสชัดเจน: Requirements → Design → Tasks
+- **GIVEN/WHEN/THEN** — Acceptance criteria แบบ Gherkin ที่ทดสอบได้
+- **Mermaid Diagrams** — Architecture และ Sequence diagrams อัตโนมัติ
+- **Traceability** — ทุก task อ้างอิงกลับไปหา requirement
+- **Progress Tracking** — `[ ]` `[/]` `[x]` สำหรับ track progress
+- **Human-in-the-Loop** — ต้อง approve ก่อนไปเฟสถัดไป
+- **3 Workflow Variants** — Requirements-First, Design-First, Bugfix Mode
+- **Agent-Compatible** — ใช้ได้กับ AI agent ทุกตัว
+
+---
+
+## โครงสร้าง Skill
+
+```
+spec-driven-dev/
+├── SKILL.md                              # คำสั่งหลัก (AI Agent อ่านไฟล์นี้)
+├── README.md                             # คู่มือนี้
+├── templates/
+│   ├── requirements.template.md          # เทมเพลต: กำหนดว่า "ทำอะไร"
+│   ├── design.template.md                # เทมเพลต: กำหนดว่า "ทำยังไง"
+│   └── tasks.template.md                 # เทมเพลต: แผนการทำงาน
+├── examples/
+│   ├── example-requirements.md           # ตัวอย่าง: Shopping Cart requirements
+│   ├── example-design.md                 # ตัวอย่าง: Shopping Cart design
+│   └── example-tasks.md                  # ตัวอย่าง: Shopping Cart tasks
+└── scripts/
+    ├── init-spec.sh                      # Script สร้าง spec ใหม่ (Linux/Mac)
+    └── init-spec.bat                     # Script สร้าง spec ใหม่ (Windows)
+```
+
+---
+
+## การติดตั้ง
+
+คัดลอกโฟลเดอร์ `spec-driven-dev` ไปวางในโฟลเดอร์ skills ของเครื่องมือที่ใช้:
+
+### Gemini CLI / Google Antigravity
+
+```powershell
+Copy-Item -Recurse "spec-driven-dev" ".gemini\skills\spec-driven-dev"
+```
+
+### Cursor
+
+```powershell
+Copy-Item -Recurse "spec-driven-dev" ".cursor\skills\spec-driven-dev"
+```
+
+### Windsurf
+
+```powershell
+Copy-Item -Recurse "spec-driven-dev" ".windsurf\skills\spec-driven-dev"
+```
+
+### เครื่องมืออื่นๆ
+
+ชี้ให้ AI agent อ่านไฟล์ `SKILL.md` โดยตรง หรือ copy เนื้อหาเข้า system prompt
+
+---
+
+## วิธีใช้งาน
+
+### วิธีที่ 1: บอก AI Agent โดยตรง
+
+พิมพ์ประโยคแบบนี้ใน chat:
+
+```
+สร้าง spec สำหรับ feature ระบบ login
+```
+
+```
+ช่วย spec feature ตะกร้าสินค้า ตาม spec-driven-dev skill
+```
+
+```
+Start a spec for user-authentication using the spec-driven-dev skill
+```
+
+Agent จะเริ่มทำตาม workflow 3 เฟสอัตโนมัติ
+
+---
+
+### วิธีที่ 2: ใช้ Script สร้างโครงสร้างก่อน
+
+```powershell
+# Windows
+.\scripts\init-spec.bat user-authentication
+
+# Linux / Mac
+bash scripts/init-spec.sh user-authentication
+```
+
+จะได้โครงสร้าง:
+
+```
+.specs/user-authentication/
+├── requirements.md    <- เทมเพลตพร้อมแก้ไข
+├── design.md          <- เทมเพลตพร้อมแก้ไข
+└── tasks.md           <- เทมเพลตพร้อมแก้ไข
+```
+
+แล้วบอก agent: `"ช่วยเติม spec ใน .specs/user-authentication/"`
+
+---
+
+## Workflow 3 เฟส
+
+```
+┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
+│    Phase 1      │      │    Phase 2      │      │    Phase 3      │
+│  REQUIREMENTS   │ -->  │     DESIGN      │ -->  │     TASKS       │
+│                 │      │                 │      │                 │
+│  กำหนดว่า       │      │  กำหนดว่า       │      │  แผนการทำงาน    │
+│  "ทำอะไร"       │      │  "ทำยังไง"      │      │  ทีละขั้นตอน     │
+│                 │      │                 │      │                 │
+│  - User Stories │      │  - Architecture │      │  - Task List    │
+│  - GIVEN/WHEN/  │      │  - Components   │      │  - Phases       │
+│    THEN         │      │  - Data Models  │      │  - Verification │
+│  - Edge Cases   │      │  - API Contracts│      │  - Status [x]   │
+└────────┬────────┘      └────────┬────────┘      └────────┬────────┘
+         │                        │                        │
+    คุณ approve              คุณ approve              คุณ approve
+                                                           │
+                                                      เริ่ม code!
+```
+
+### เฟส 1 — Requirements (`requirements.md`)
+
+กำหนด **"ทำอะไร"** จากมุมมองผู้ใช้
+
+```markdown
+# Feature: ระบบ Login
+
+## User Story
+**As a** ผู้ใช้ทั่วไป,
+**I want to** เข้าสู่ระบบด้วย email และ password,
+**so that** ฉันสามารถเข้าถึงข้อมูลส่วนตัวของฉันได้.
+
+## Acceptance Criteria
+
+### AC-1.1: เข้าสู่ระบบสำเร็จ
+**Given** ผู้ใช้อยู่ที่หน้า login
+**And** มีบัญชีอยู่แล้วในระบบ
+**When** กรอก email และ password ที่ถูกต้อง แล้วกดปุ่ม "Login"
+**Then** ระบบพาไปหน้า dashboard
+**And** แสดงชื่อผู้ใช้ที่มุมบนขวา
+
+### AC-1.2: กรอก password ผิด
+**Given** ผู้ใช้อยู่ที่หน้า login
+**When** กรอก email ถูกต้อง แต่ password ผิด
+**Then** แสดงข้อความ "อีเมลหรือรหัสผ่านไม่ถูกต้อง"
+**And** ไม่บอกว่าผิดอันไหน (เพื่อความปลอดภัย)
+```
+
+**คุณรีวิว -> แก้ไข -> approve** -> ไปเฟส 2
+
+---
+
+### เฟส 2 — Design (`design.md`)
+
+กำหนด **"ทำยังไง"** ในเชิงเทคนิค
+
+```markdown
+## Architecture
+┌──────────┐     ┌──────────┐     ┌──────────┐
+│  React   │ --> │  Express │ --> │ Postgres │
+│  Frontend│     │  API     │     │ Database │
+└──────────┘     └──────────┘     └──────────┘
+
+## Component: AuthService
+- Responsibility: จัดการ login, logout, token refresh
+- Location: src/server/services/AuthService.ts
+
+## API Contract
+POST /api/auth/login
+Request:  { "email": "string", "password": "string" }
+Response: { "token": "jwt", "user": { "id", "name" } }
+```
+
+**คุณรีวิว -> แก้ไข -> approve** -> ไปเฟส 3
+
+---
+
+### เฟส 3 — Tasks (`tasks.md`)
+
+แผนการทำงานเป็น **checklist**
+
+```markdown
+## Phase 1: Database
+- [x] Task 1.1: สร้าง users table migration
+- [x] Task 1.2: สร้าง User model
+
+## Phase 2: Backend API
+- [/] Task 2.1: สร้าง POST /api/auth/login     <- กำลังทำ
+- [ ] Task 2.2: สร้าง JWT middleware
+- [ ] Task 2.3: สร้าง rate limiting
+
+## Phase 3: Frontend
+- [ ] Task 3.1: สร้าง LoginForm component
+- [ ] Task 3.2: สร้าง auth context/store
+- [ ] Task 3.3: สร้าง protected route
+
+## Phase 4: Testing
+- [ ] Task 4.1: Unit tests สำหรับ AuthService
+- [ ] Task 4.2: E2E test login flow
+```
+
+**คุณ approve -> Agent เริ่ม code ทีละ task**
+
+---
+
+## Workflow Variants
+
+### 1. Requirements-First (ค่าเริ่มต้น)
+
+เหมาะกับ **feature ใหม่** ที่เน้น business logic
+
+```
+requirements.md -> design.md -> tasks.md
+```
+
+**ใช้เมื่อ:** สร้างฟีเจอร์ใหม่ตั้งแต่ต้น
+
+---
+
+### 2. Design-First
+
+เหมาะกับ **ระบบซับซ้อน** ที่มีข้อจำกัดทางเทคนิค
+
+```
+design.md -> requirements.md (derived) -> tasks.md
+```
+
+**ใช้เมื่อ:** มี architecture constraints, performance requirements, หรือต้อง integrate กับระบบเดิม
+
+---
+
+### 3. Bugfix Mode
+
+เหมาะกับ **bug ที่ซับซ้อน** ต้องวิเคราะห์ root cause
+
+```
+bugfix.md -> design.md (root cause + fix) -> tasks.md
+```
+
+**ใช้เมื่อ:** Bug ที่ reproduce ยาก หรือเกี่ยวข้องหลาย component
+
+---
+
+## ตัวอย่างคำสั่งสำหรับ AI Agent
+
+| สถานการณ์ | พูดกับ Agent ว่า |
+|----------|-----------------|
+| เริ่ม feature ใหม่ | `"สร้าง spec สำหรับ feature [ชื่อ]"` |
+| Fix bug ซับซ้อน | `"สร้าง bugfix spec สำหรับ [ปัญหา]"` |
+| มี design อยู่แล้ว | `"เริ่มจาก design-first สำหรับ [ชื่อ]"` |
+| Approve เฟส | `"approve แล้ว ไปเฟสถัดไป"` |
+| เริ่ม code | `"approve tasks แล้ว เริ่ม execute ได้เลย"` |
+| แก้ requirement | `"แก้ AC-1.2 เป็น... แล้ว sync ลง tasks"` |
+| ดูตัวอย่าง | `"ดูตัวอย่าง requirements จาก examples"` |
+| สร้างจากเทมเพลต | `"สร้าง requirements จาก template"` |
+
+---
+
+## Output ที่ได้
+
+เมื่อใช้ skill นี้กับ project จะได้โครงสร้าง:
+
+```
+your-project/
+├── .specs/
+│   ├── user-authentication/
+│   │   ├── requirements.md       <- Approved
+│   │   ├── design.md             <- Approved
+│   │   └── tasks.md              <- In Progress (12/15 tasks done)
+│   │
+│   ├── shopping-cart/
+│   │   ├── requirements.md       <- Approved
+│   │   ├── design.md             <- Draft
+│   │   └── tasks.md              <- Not Started
+│   │
+│   └── payment-integration/
+│       └── requirements.md       <- Draft
+│
+├── src/
+│   └── ...                       <- code ที่สร้างจาก tasks
+└── ...
+```
+
+---
+
+## หลักการสำคัญ
+
+| หลักการ | คำอธิบาย |
+|---------|---------|
+| **Plan First** | วางแผนก่อน code เสมอ |
+| **Traceability** | ทุก task อ้างอิงกลับไป requirement |
+| **Human-in-the-Loop** | คนต้อง approve ก่อนทุกเฟส |
+| **Small Tasks** | แต่ละ task เล็กพอทำจบได้ในรอบเดียว |
+| **Living Documentation** | Spec อัปเดตตาม code ที่เปลี่ยน |
+| **Verify Often** | ทุกเฟสมี verification step |
+
+---
+
+## ไฟล์ Reference
+
+| ไฟล์ | คำอธิบาย |
+|------|---------|
+| [`SKILL.md`](./SKILL.md) | คำสั่งหลักที่ AI Agent อ่าน |
+| [`templates/requirements.template.md`](./templates/requirements.template.md) | เทมเพลต requirements |
+| [`templates/design.template.md`](./templates/design.template.md) | เทมเพลต design |
+| [`templates/tasks.template.md`](./templates/tasks.template.md) | เทมเพลต tasks |
+| [`examples/example-requirements.md`](./examples/example-requirements.md) | ตัวอย่าง requirements (Shopping Cart) |
+| [`examples/example-design.md`](./examples/example-design.md) | ตัวอย่าง design (Shopping Cart) |
+| [`examples/example-tasks.md`](./examples/example-tasks.md) | ตัวอย่าง tasks (Shopping Cart) |
+
+---
+
+## Compatibility
+
+| เครื่องมือ | รองรับ | วิธีติดตั้ง |
+|-----------|-------|-----------|
+| Google Antigravity / Gemini CLI | Yes | `.gemini/skills/` |
+| Cursor | Yes | `.cursor/skills/` |
+| Windsurf | Yes | `.windsurf/skills/` |
+| Claude (Anthropic) | Yes | ใส่ SKILL.md ใน system prompt |
+| ChatGPT / GPT-4 | Yes | ใส่ SKILL.md ใน system prompt |
+| GitHub Copilot | Yes | `.github/copilot/skills/` |
+| อื่นๆ | Yes | อ้างอิง SKILL.md โดยตรง |
+
+---
+
+<p align="center">
+  <b>Spec-Driven Development</b> — Stop vibe coding. Start spec coding.
+</p>

package/skill/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: spec-driven-dev
+description: >
+  Spec-Driven Development (SDD) skill inspired by Kiro IDE.
+  Enforces a structured 3-phase workflow: Requirements → Design → Tasks.
+  Use this skill when starting a new feature, refactoring, or fixing a complex bug.
+  It ensures AI agents plan first, then build — reducing ambiguity, improving code quality,
+  and creating living documentation that stays in sync with the codebase.
+---
+
+# Spec-Driven Development (SDD)
+
+> **Philosophy:** Plan first, then build. Create requirements and design before coding starts.
+
+This skill implements a structured, spec-driven development workflow inspired by Kiro IDE.
+Every feature, refactor, or complex bugfix follows **three phases**, each producing a
+living Markdown document that serves as the source of truth for AI agents and human developers alike.
+
+---
+
+## When to Use This Skill
+
+- Thinking through features in-depth
+- Projects needing upfront planning
+- Building features in a structured way
+- Complex bug fixes requiring root-cause analysis
+- Refactoring with clear scope and success criteria
+
+---
+
+## Directory Structure
+
+All spec documents live under a `.specs/` directory at the project root, organized by feature:
+
+```
+.specs/
+└── <feature-name>/
+    ├── requirements.md    # Phase 1: WHAT to build
+    ├── design.md          # Phase 2: HOW to build it
+    └── tasks.md           # Phase 3: Execution plan
+```
+
+---
+
+## The 3-Phase Workflow
+
+### Phase 1 → Requirements (`requirements.md`)
+
+**Goal:** Define *what* needs to be built or fixed.
+
+1. Read the template: [templates/requirements.template.md](templates/requirements.template.md)
+2. Gather the user's high-level intent and translate it into structured **User Stories** and **Acceptance Criteria**.
+3. Use the **GIVEN / WHEN / THEN** format (Gherkin-style) for every acceptance criterion.
+4. Keep language **non-technical** — focus on behavior from the user's perspective.
+5. Cover **happy paths**, **edge cases**, and **error scenarios**.
+
+**Transition Rule:** Do NOT proceed to Phase 2 until the user has reviewed and approved the requirements.
+
+---
+
+### Phase 2 → Design (`design.md`)
+
+**Goal:** Define *how* to build it.
+
+1. Read the template: [templates/design.template.md](templates/design.template.md)
+2. Map each requirement to a **technical solution**.
+3. Define: architecture, components, data models, API contracts, and error-handling strategies.
+4. Use **Mermaid diagrams** for system architecture and sequence diagrams where applicable.
+5. List **constraints**, **forbidden patterns**, and **naming conventions**.
+6. Identify **technical risks** and **open questions**.
+
+**Transition Rule:** Do NOT proceed to Phase 3 until the user has reviewed and approved the design.
+
+---
+
+### Phase 3 → Tasks (`tasks.md`)
+
+**Goal:** Define the step-by-step execution plan.
+
+1. Read the template: [templates/tasks.template.md](templates/tasks.template.md)
+2. Break the design into **discrete, trackable, executable tasks**.
+3. Group tasks into **logical phases** (e.g., Database → Backend → Frontend → Testing).
+4. Use checkbox syntax for status tracking:
+   - `- [ ]` → Not started
+   - `- [/]` → In progress
+   - `- [x]` → Completed
+5. Each task should be **small enough to complete in one focused session**.
+6. Include **sub-tasks** for complex items.
+7. Add **verification steps** at the end of each phase.
+
+**Transition Rule:** Execute tasks one at a time (or in approved parallel batches). Update status as you go.
+
+---
+
+## Workflow Variants
+
+### 🔹 Requirements-First (Default)
+Best for **new features** where business logic is the priority.
+Flow: `requirements.md` → `design.md` → `tasks.md`
+
+### 🔹 Design-First
+Best for **complex systems** or scenarios with strict technical constraints.
+Flow: `design.md` → `requirements.md` (derived) → `tasks.md`
+
+### 🔹 Bugfix Mode
+For **complex bugs** requiring root-cause analysis.
+Use `requirements.md` as a `bugfix.md` with:
+- **Bug Description** instead of User Story
+- **Reproduction Steps** in GIVEN/WHEN/THEN format
+- **Expected vs Actual Behavior**
+- **Root Cause Analysis** section in `design.md`
+
+---
+
+## Agent Instructions
+
+When activated, follow this exact sequence:
+
+### Step 1: Initialize
+```
+1. Ask the user: "What feature/fix would you like to spec out?"
+2. Determine the workflow variant (Requirements-First, Design-First, or Bugfix)
+3. Create the `.specs/<feature-name>/` directory
+```
+
+### Step 2: Requirements Phase
+```
+1. Generate `requirements.md` using the template
+2. Present to user for review
+3. Iterate until user approves
+4. Mark phase as complete
+```
+
+### Step 3: Design Phase
+```
+1. Generate `design.md` using the template, referencing approved requirements
+2. Include architecture diagrams (Mermaid)
+3. Present to user for review
+4. Iterate until user approves
+5. Mark phase as complete
+```
+
+### Step 4: Tasks Phase
+```
+1. Generate `tasks.md` using the template, referencing approved design
+2. Break into small, actionable items with clear acceptance
+3. Present to user for review
+4. Iterate until user approves
+5. Begin execution when user says "go" or "start"
+```
+
+### Step 5: Execution
+```
+1. Pick the next uncompleted task
+2. Update its status to [/] (in progress)
+3. Implement the task
+4. Run verification (tests, build, lint)
+5. Update status to [x] (completed)
+6. Repeat until all tasks are done
+```
+
+### Step 6: Sync (When Changes Occur)
+```
+If requirements or design change mid-development:
+1. Update the changed document
+2. Cascade changes to downstream documents
+3. Re-verify affected completed tasks
+4. Get user approval before continuing
+```
+
+---
+
+## Key Principles
+
+| Principle | Description |
+|-----------|-------------|
+| **Traceability** | Every task links back to a requirement and design element |
+| **Living Docs** | Spec files are updated as the project evolves |
+| **Human-in-the-Loop** | User approves each phase before the next begins |
+| **Small Tasks** | Each task is completable in one focused session |
+| **Verify Often** | Every phase includes verification steps |
+
+---
+
+## File Reference
+
+| File | Purpose |
+|------|---------|
+| [templates/requirements.template.md](templates/requirements.template.md) | Requirements template with GIVEN/WHEN/THEN format |
+| [templates/design.template.md](templates/design.template.md) | Technical design template with architecture diagrams |
+| [templates/tasks.template.md](templates/tasks.template.md) | Task breakdown template with status tracking |
+| [examples/example-requirements.md](examples/example-requirements.md) | Complete example: E-commerce cart requirements |
+| [examples/example-design.md](examples/example-design.md) | Complete example: E-commerce cart design |
+| [examples/example-tasks.md](examples/example-tasks.md) | Complete example: E-commerce cart tasks |
+