@panuwatbas/spec-driven-dev 1.0.2

package/skill/scripts/init-spec.sh

@@ -0,0 +1,159 @@
+#!/usr/bin/env bash
+# ============================================================================
+# init-spec.sh — Initialize a new spec directory for a feature
+#
+# Usage:
+#   bash .specs/scripts/init-spec.sh <feature-name> [--bugfix]
+#
+# Examples:
+#   bash .specs/scripts/init-spec.sh user-authentication
+#   bash .specs/scripts/init-spec.sh login-crash --bugfix
+# ============================================================================
+
+set -euo pipefail
+
+# --- Configuration ---
+SPECS_DIR=".specs"
+SKILL_DIR=""
+
+# Find the skill templates directory
+# Check common locations
+for dir in \
+  ".gemini/skills/spec-driven-dev/templates" \
+  "skills/spec-driven-dev/templates" \
+  ".cursor/skills/spec-driven-dev/templates" \
+  ; do
+  if [ -d "$dir" ]; then
+    SKILL_DIR="$dir"
+    break
+  fi
+done
+
+# --- Parse Arguments ---
+FEATURE_NAME="${1:-}"
+MODE="feature"
+
+if [ -z "$FEATURE_NAME" ]; then
+  echo "❌ Error: Feature name is required."
+  echo ""
+  echo "Usage: bash $0 <feature-name> [--bugfix]"
+  echo ""
+  echo "Examples:"
+  echo "  bash $0 user-authentication"
+  echo "  bash $0 login-crash --bugfix"
+  exit 1
+fi
+
+if [ "${2:-}" = "--bugfix" ]; then
+  MODE="bugfix"
+fi
+
+# --- Create Directory ---
+SPEC_PATH="$SPECS_DIR/$FEATURE_NAME"
+
+if [ -d "$SPEC_PATH" ]; then
+  echo "⚠️  Spec directory already exists: $SPEC_PATH"
+  echo "   Use the existing spec or choose a different name."
+  exit 1
+fi
+
+mkdir -p "$SPEC_PATH"
+echo "📁 Created: $SPEC_PATH/"
+
+# --- Copy Templates ---
+if [ -n "$SKILL_DIR" ]; then
+  cp "$SKILL_DIR/requirements.template.md" "$SPEC_PATH/requirements.md"
+  cp "$SKILL_DIR/design.template.md" "$SPEC_PATH/design.md"
+  cp "$SKILL_DIR/tasks.template.md" "$SPEC_PATH/tasks.md"
+  echo "📄 Copied templates from $SKILL_DIR"
+else
+  # Create minimal files if templates not found
+  cat > "$SPEC_PATH/requirements.md" << 'EOF'
+# Feature: [Feature Name]
+
+> **Status:** 🟡 Draft
+
+## Overview
+
+[Describe the feature here.]
+
+## User Stories
+
+### US-1: [Story Title]
+
+**As a** [persona],
+**I want to** [action],
+**so that** [benefit].
+
+#### Acceptance Criteria
+
+##### AC-1.1: [Scenario]
+
+**Given** [precondition]
+**When** [action]
+**Then** [outcome]
+EOF
+
+  cat > "$SPEC_PATH/design.md" << 'EOF'
+# Technical Design: [Feature Name]
+
+> **Status:** 🟡 Draft
+
+## Overview
+
+[Describe the technical approach here.]
+
+## Architecture
+
+[Define the architecture.]
+
+## Component Design
+
+[Define the components.]
+EOF
+
+  cat > "$SPEC_PATH/tasks.md" << 'EOF'
+# Implementation Tasks: [Feature Name]
+
+> **Status:** 🟡 Not Started
+
+## Phase 1: [Foundation]
+
+- [ ] **Task 1.1:** [Description]
+- [ ] **Task 1.2 (Verify):** Verification
+
+## Phase 2: [Core Logic]
+
+- [ ] **Task 2.1:** [Description]
+- [ ] **Task 2.2 (Verify):** Verification
+EOF
+
+  echo "📄 Created minimal spec files (templates not found)"
+fi
+
+# --- Replace Placeholders ---
+DATE=$(date +%Y-%m-%d)
+TITLE=$(echo "$FEATURE_NAME" | sed 's/-/ /g' | sed 's/\b\w/\u&/g')
+
+if [[ "$OSTYPE" == "darwin"* ]]; then
+  SED_CMD="sed -i ''"
+else
+  SED_CMD="sed -i"
+fi
+
+for file in "$SPEC_PATH"/*.md; do
+  $SED_CMD "s/\[Feature Name\]/$TITLE/g" "$file" 2>/dev/null || true
+  $SED_CMD "s/\[Date\]/$DATE/g" "$file" 2>/dev/null || true
+done
+
+# --- Summary ---
+echo ""
+echo "✅ Spec initialized for: $FEATURE_NAME"
+echo ""
+echo "📋 Next steps:"
+echo "   1. Edit $SPEC_PATH/requirements.md — Define WHAT to build"
+echo "   2. Edit $SPEC_PATH/design.md       — Define HOW to build it"
+echo "   3. Edit $SPEC_PATH/tasks.md        — Define the execution plan"
+echo ""
+echo "💡 Or ask your AI agent:"
+echo "   \"Start a spec for $FEATURE_NAME using the spec-driven-dev skill\""

package/skill/templates/design.template.md

@@ -0,0 +1,248 @@
+# Technical Design: [Feature Name]
+
+> **Status:** 🟡 Draft | 🟢 Approved | 🔴 Needs Revision
+>
+> **Requirements:** [Link to requirements.md](../requirements.md)
+>
+> **Author:** [Name / AI Agent]
+>
+> **Created:** [Date]
+>
+> **Last Updated:** [Date]
+
+---
+
+## 1. Overview
+
+<!-- 2-3 sentence summary of the technical approach. What is the architectural strategy? -->
+
+[Describe the high-level technical approach here.]
+
+---
+
+## 2. Architecture
+
+### 2.1 System Diagram
+
+```mermaid
+graph TD
+    A[Client / UI] --> B[API Layer]
+    B --> C[Business Logic]
+    C --> D[(Database)]
+    C --> E[External Service]
+```
+
+### 2.2 Architectural Pattern
+
+<!-- e.g., MVC, Microservices, Event-Driven, Serverless, Monolith -->
+
+[Describe the chosen pattern and justify the decision.]
+
+### 2.3 Tech Stack
+
+| Layer | Technology | Justification |
+|-------|-----------|---------------|
+| Frontend | [e.g., React, Vue] | [Why this choice] |
+| Backend | [e.g., Node.js, Python] | [Why this choice] |
+| Database | [e.g., PostgreSQL, MongoDB] | [Why this choice] |
+| Hosting | [e.g., Vercel, AWS] | [Why this choice] |
+
+---
+
+## 3. Component Design
+
+### 3.1 [Component Name A]
+
+- **Responsibility:** [Single-sentence description of this component's job]
+- **Location:** `src/components/ComponentA/`
+- **Public Interface:**
+  ```typescript
+  // Example API / function signatures
+  interface ComponentAProps {
+    data: DataType;
+    onAction: (id: string) => void;
+  }
+  ```
+- **State Management:** [How data flows in/out]
+- **Dependencies:** [What this component depends on]
+
+### 3.2 [Component Name B]
+
+- **Responsibility:** [Single-sentence description]
+- **Location:** `src/services/ServiceB/`
+- **Public Interface:**
+  ```typescript
+  class ServiceB {
+    async getData(id: string): Promise<DataType> {}
+    async updateData(id: string, payload: UpdatePayload): Promise<void> {}
+  }
+  ```
+- **Error Handling:** [How errors are managed]
+
+<!-- Add more components as needed -->
+
+---
+
+## 4. Data Models
+
+### 4.1 [Entity Name]
+
+```typescript
+interface EntityName {
+  id: string;              // UUID, primary key
+  name: string;            // Display name
+  status: 'active' | 'inactive';
+  createdAt: Date;
+  updatedAt: Date;
+}
+```
+
+### 4.2 Database Schema
+
+```sql
+CREATE TABLE entity_name (
+  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name        VARCHAR(255) NOT NULL,
+  status      VARCHAR(20) DEFAULT 'active',
+  created_at  TIMESTAMP DEFAULT NOW(),
+  updated_at  TIMESTAMP DEFAULT NOW()
+);
+```
+
+<!-- Add more data models as needed -->
+
+---
+
+## 5. API Contracts
+
+### 5.1 [Endpoint Name]
+
+| Property | Value |
+|----------|-------|
+| Method | `POST` |
+| Path | `/api/v1/resource` |
+| Auth | Required (Bearer token) |
+
+**Request Body:**
+```json
+{
+  "name": "string",
+  "description": "string (optional)"
+}
+```
+
+**Response (200):**
+```json
+{
+  "id": "uuid",
+  "name": "string",
+  "createdAt": "ISO-8601"
+}
+```
+
+**Error Responses:**
+
+| Status | Description |
+|--------|-------------|
+| 400 | Invalid input — missing required fields |
+| 401 | Unauthorized — invalid or missing token |
+| 409 | Conflict — resource already exists |
+
+<!-- Add more endpoints as needed -->
+
+---
+
+## 6. Sequence Diagrams
+
+### 6.1 [Flow Name — e.g., User Creates Resource]
+
+```mermaid
+sequenceDiagram
+    actor User
+    participant UI as Frontend
+    participant API as API Server
+    participant DB as Database
+
+    User->>UI: Fills form and clicks Submit
+    UI->>API: POST /api/v1/resource
+    API->>API: Validate input
+    API->>DB: INSERT INTO resource
+    DB-->>API: Success
+    API-->>UI: 201 Created
+    UI-->>User: Show success message
+```
+
+<!-- Add more sequence diagrams as needed -->
+
+---
+
+## 7. Error Handling Strategy
+
+| Error Type | Handling Approach |
+|-----------|-------------------|
+| Validation errors | Return 400 with field-level error messages |
+| Auth errors | Return 401/403, redirect to login |
+| Not found | Return 404 with descriptive message |
+| Server errors | Return 500, log to monitoring, show generic message to user |
+| Network errors | Retry with exponential backoff (max 3 attempts) |
+
+---
+
+## 8. Testing Strategy
+
+| Level | Tool | Coverage Target |
+|-------|------|----------------|
+| Unit Tests | [e.g., Jest, Vitest] | Core business logic |
+| Integration Tests | [e.g., Supertest] | API endpoints |
+| E2E Tests | [e.g., Playwright, Cypress] | Critical user flows |
+
+---
+
+## 9. Security Considerations
+
+- [ ] Input validation and sanitization on all endpoints
+- [ ] Authentication required for protected routes
+- [ ] Rate limiting on public endpoints
+- [ ] Sensitive data encrypted at rest
+- [ ] CORS properly configured
+- [ ] SQL injection prevention (parameterized queries)
+- [ ] XSS prevention (output encoding)
+
+---
+
+## 10. Constraints & Rules
+
+### Forbidden Patterns
+- ❌ No global mutable state
+- ❌ No direct DOM manipulation (use framework reactivity)
+- ❌ No hardcoded secrets or credentials
+- ❌ No `any` type in TypeScript (use proper typing)
+
+### Naming Conventions
+- Files: `kebab-case.ts`
+- Components: `PascalCase`
+- Functions: `camelCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Database tables: `snake_case`
+
+### Code Quality
+- Max function length: 50 lines
+- Max file length: 300 lines
+- All public functions must have JSDoc comments
+
+---
+
+## 11. Open Questions
+
+<!-- Technical questions that need resolution before or during implementation. -->
+
+- [ ] [Technical question 1]
+- [ ] [Technical question 2]
+
+---
+
+## 12. Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 0.1 | [Date] | [Author] | Initial design |

package/skill/templates/requirements.template.md

@@ -0,0 +1,116 @@
+# Feature: [Feature Name]
+
+> **Status:** 🟡 Draft | 🟢 Approved | 🔴 Needs Revision
+>
+> **Author:** [Name / AI Agent]
+>
+> **Created:** [Date]
+>
+> **Last Updated:** [Date]
+
+---
+
+## Overview
+
+<!-- Brief 2-3 sentence summary of the feature. What problem does it solve? Why is it needed? -->
+
+[Describe the feature at a high level here.]
+
+---
+
+## User Stories
+
+### US-1: [Primary User Story Title]
+
+**As a** [persona / role],
+**I want to** [action / goal],
+**so that** [benefit / business value].
+
+#### Acceptance Criteria
+
+##### AC-1.1: [Scenario Title — Happy Path]
+
+**Given** [the initial context or precondition]
+**And** [additional precondition, if any]
+**When** [the action or event occurs]
+**Then** [the expected outcome or result]
+**And** [additional expected outcome, if any]
+
+##### AC-1.2: [Scenario Title — Edge Case]
+
+**Given** [the initial context or precondition]
+**When** [the action or event occurs]
+**Then** [the expected outcome or result]
+
+##### AC-1.3: [Scenario Title — Error Case]
+
+**Given** [the initial context or precondition]
+**When** [an invalid action or bad input occurs]
+**Then** [the expected error handling behavior]
+**And** [the system remains in a valid state]
+
+---
+
+### US-2: [Secondary User Story Title]
+
+**As a** [persona / role],
+**I want to** [action / goal],
+**so that** [benefit / business value].
+
+#### Acceptance Criteria
+
+##### AC-2.1: [Scenario Title]
+
+**Given** [precondition]
+**When** [action]
+**Then** [outcome]
+
+<!-- Add more user stories and acceptance criteria as needed -->
+
+---
+
+## Out of Scope
+
+<!-- Explicitly list what this feature does NOT include to prevent scope creep. -->
+
+- [Item 1 — explain why it's excluded]
+- [Item 2 — explain why it's excluded]
+
+---
+
+## Dependencies
+
+<!-- List any external systems, APIs, services, or other features this depends on. -->
+
+| Dependency | Type | Status |
+|-----------|------|--------|
+| [Dependency 1] | [API / Service / Feature] | [Available / Planned] |
+| [Dependency 2] | [API / Service / Feature] | [Available / Planned] |
+
+---
+
+## Non-Functional Requirements
+
+<!-- Performance, security, accessibility, or other quality attributes. -->
+
+- **Performance:** [e.g., Page must load in < 2 seconds]
+- **Security:** [e.g., All inputs must be sanitized]
+- **Accessibility:** [e.g., Must meet WCAG 2.1 AA standards]
+- **Browser Support:** [e.g., Chrome, Firefox, Safari latest 2 versions]
+
+---
+
+## Open Questions
+
+<!-- List any unresolved questions that need stakeholder input. -->
+
+- [ ] [Question 1]
+- [ ] [Question 2]
+
+---
+
+## Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 0.1 | [Date] | [Author] | Initial draft |

package/skill/templates/tasks.template.md

@@ -0,0 +1,127 @@
+# Implementation Tasks: [Feature Name]
+
+> **Status:** 🟡 Not Started | 🔵 In Progress | 🟢 Completed
+>
+> **Requirements:** [Link to requirements.md](../requirements.md)
+>
+> **Design:** [Link to design.md](../design.md)
+>
+> **Created:** [Date]
+>
+> **Last Updated:** [Date]
+
+---
+
+## Progress Overview
+
+| Phase | Status | Tasks | Completed |
+|-------|--------|-------|-----------|
+| Phase 1: [Name] | ⬜ Not Started | 0/0 | 0% |
+| Phase 2: [Name] | ⬜ Not Started | 0/0 | 0% |
+| Phase 3: [Name] | ⬜ Not Started | 0/0 | 0% |
+| Phase 4: [Name] | ⬜ Not Started | 0/0 | 0% |
+
+---
+
+## Phase 1: [Foundation / Setup / Database]
+
+> **Goal:** [What this phase accomplishes]
+>
+> **Traces to:** [US-1, AC-1.1] from requirements.md
+
+- [ ] **Task 1.1:** [Clear, actionable task description]
+  - File(s): `path/to/file.ts`
+  - Details: [Implementation specifics, if needed]
+  - [ ] Sub-task 1.1.1: [Smaller step if task is complex]
+  - [ ] Sub-task 1.1.2: [Smaller step if task is complex]
+
+- [ ] **Task 1.2:** [Clear, actionable task description]
+  - File(s): `path/to/file.ts`
+  - Details: [Implementation specifics]
+
+- [ ] **Task 1.3 (Verify):** Run verification for Phase 1
+  - [ ] All new files compile without errors
+  - [ ] Unit tests pass for Phase 1 components
+  - [ ] [Any phase-specific verification]
+
+---
+
+## Phase 2: [Core Logic / Backend / API]
+
+> **Goal:** [What this phase accomplishes]
+>
+> **Traces to:** [US-1, AC-1.2, AC-1.3] from requirements.md
+
+- [ ] **Task 2.1:** [Clear, actionable task description]
+  - File(s): `path/to/file.ts`
+  - Details: [Implementation specifics]
+
+- [ ] **Task 2.2:** [Clear, actionable task description]
+  - File(s): `path/to/file.ts`
+  - Details: [Implementation specifics]
+
+- [ ] **Task 2.3 (Verify):** Run verification for Phase 2
+  - [ ] API endpoints return correct responses
+  - [ ] Error cases handled properly
+  - [ ] Integration tests pass
+
+---
+
+## Phase 3: [Frontend / UI / Integration]
+
+> **Goal:** [What this phase accomplishes]
+>
+> **Traces to:** [US-2, AC-2.1] from requirements.md
+
+- [ ] **Task 3.1:** [Clear, actionable task description]
+  - File(s): `path/to/file.tsx`
+  - Details: [Implementation specifics]
+
+- [ ] **Task 3.2:** [Clear, actionable task description]
+  - File(s): `path/to/file.tsx`
+  - Details: [Implementation specifics]
+
+- [ ] **Task 3.3 (Verify):** Run verification for Phase 3
+  - [ ] UI renders correctly
+  - [ ] User interactions work as expected
+  - [ ] Responsive on all target screen sizes
+
+---
+
+## Phase 4: [Testing / Polish / Deployment]
+
+> **Goal:** Final verification and cleanup
+
+- [ ] **Task 4.1:** Write/update end-to-end tests
+  - [ ] Happy path test
+  - [ ] Edge case tests
+  - [ ] Error scenario tests
+
+- [ ] **Task 4.2:** Code quality review
+  - [ ] No lint warnings
+  - [ ] No TypeScript errors
+  - [ ] All functions documented
+
+- [ ] **Task 4.3:** Final integration verification
+  - [ ] All phases verified
+  - [ ] All acceptance criteria from requirements.md met
+  - [ ] No regressions in existing functionality
+
+---
+
+## Task Status Legend
+
+| Symbol | Meaning |
+|--------|---------|
+| `- [ ]` | Not started |
+| `- [/]` | In progress |
+| `- [x]` | Completed |
+| `- [!]` | Blocked / Needs attention |
+
+---
+
+## Notes
+
+<!-- Add any implementation notes, discoveries, or decisions made during execution. -->
+
+- [Date]: [Note about a decision or discovery]