spec-lite 1.0.0

package/bin/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { cpSync, mkdirSync, existsSync } from 'fs'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const cwd = process.cwd()
+const [,, command] = process.argv
+
+if (command === 'install') {
+  const pkgRoot = join(__dirname, '..')
+  const claudeDir = join(cwd, '.claude')
+
+  mkdirSync(claudeDir, { recursive: true })
+
+  // Copy skills → .claude/skills/
+  cpSync(join(pkgRoot, 'skills'), join(claudeDir, 'skills'), { recursive: true })
+  console.log('✓ skills  →  .claude/skills/')
+
+  // Copy templates → .claude/templates/
+  cpSync(join(pkgRoot, 'templates'), join(claudeDir, 'templates'), { recursive: true })
+  console.log('✓ templates  →  .claude/templates/')
+} else {
+  console.log('Usage: npx @torus-engineering/spec-lite install')
+  process.exit(1)
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "spec-lite",
+  "version": "1.0.0",
+  "description": "Spec-driven development kit for Claude Code",
+  "type": "module",
+  "bin": {
+    "spec-lite": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "templates/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/planning-and-task-breakdown/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: planning-and-task-breakdown
+description: Breaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.
+---
+
+# Planning and Task Breakdown
+
+## Overview
+
+Decompose work into small, verifiable tasks with explicit acceptance criteria. Good task breakdown is the difference between an agent that completes work reliably and one that produces a tangled mess. Every task should be small enough to implement, test, and verify in a single focused session.
+
+## When to Use
+
+- You have a spec and need to break it into implementable units
+- A task feels too large or vague to start
+- Work needs to be parallelized across multiple agents or sessions
+- You need to communicate scope to a human
+- The implementation order isn't obvious
+
+**When NOT to use:** Single-file changes with obvious scope, or when the spec already contains well-defined tasks.
+
+## The Planning Process
+
+### Step 1: Enter Plan Mode
+
+Before writing any code, operate in read-only mode:
+
+- Read the spec and relevant codebase sections
+- Identify existing patterns and conventions
+- Map dependencies between components
+- Note risks and unknowns
+
+**Do NOT write code during planning.** The output is a plan document, not implementation.
+
+### Step 2: Identify the Dependency Graph
+
+Map what depends on what:
+
+```
+Database schema
+    │
+    ├── API models/types
+    │       │
+    │       ├── API endpoints
+    │       │       │
+    │       │       └── Frontend API client
+    │       │               │
+    │       │               └── UI components
+    │       │
+    │       └── Validation logic
+    │
+    └── Seed data / migrations
+```
+
+Implementation order follows the dependency graph bottom-up: build foundations first.
+
+### Step 3: Slice Vertically
+
+Instead of building all the database, then all the API, then all the UI — build one complete feature path at a time:
+
+**Bad (horizontal slicing):**
+```
+Task 1: Build entire database schema
+Task 2: Build all API endpoints
+Task 3: Build all UI components
+Task 4: Connect everything
+```
+
+**Good (vertical slicing):**
+```
+Task 1: User can create an account (schema + API + UI for registration)
+Task 2: User can log in (auth schema + API + UI for login)
+Task 3: User can create a task (task schema + API + UI for creation)
+Task 4: User can view task list (query + API + UI for list view)
+```
+
+Each vertical slice delivers working, testable functionality.
+
+### Step 4: Write Tasks
+
+Each task follows this structure:
+
+```markdown
+#### T001 — [Short descriptive title, starts with a verb]
+
+[One paragraph describing what this task delivers]
+
+**depends:** [T-IDs this task depends on, or —]
+**verify:** [AC-001, AC-002] [specific test cases that must pass — e.g. unit tests: valid input, missing field 400]
+```
+
+**`verify:` field rules:**
+
+| Task type | verify? | Example |
+|-----------|---------|---------|
+| Has behavior (service, endpoint, validation) | Yes — specific unit tests | `**verify:** [AC-001] unit tests — valid input, missing field 400, duplicate 409` |
+| Pure infrastructure (migration, config) | Yes — smoke check | `**verify:** migration runs clean, rollback succeeds` |
+| Task IS the test (Verification phase) | Yes — result | `**verify:** integration tests pass — happy path + error cases` |
+| No behavior (docs, rename, comment) | No | *(omit field)* |
+
+Rule: add `verify:` when *"if this code were deleted, which test would fail?"* can be answered. Must be specific enough for an agent to know what to write — not just "tests pass". Reference AC IDs when the task covers specific criteria.
+
+### Step 5: Order and Phases
+
+Arrange tasks so that:
+
+1. Dependencies are satisfied (build foundation first)
+2. Each task leaves the system in a working state
+3. High-risk tasks are early (fail fast)
+
+**Final phase is always Verification** — contains integration/e2e tests that can only be written after all components are complete. Replace checkpoint markers with this phase:
+
+```markdown
+### Phase N: Verification
+
+#### T00N — [integration test description]
+
+[Describe the end-to-end flow being tested]
+
+**depends:** T001, T002, ...
+**verify:** integration tests pass — [happy path + error cases spanning multiple components]
+```
+
+## Task Sizing Guidelines
+
+| Size | Files | Scope | Example |
+|------|-------|-------|---------|
+| **XS** | 1 | Single function or config change | Add a validation rule |
+| **S** | 1-2 | One component or endpoint | Add a new API endpoint |
+| **M** | 3-5 | One feature slice | User registration flow |
+| **L** | 5-8 | Multi-component feature | Search with filtering and pagination |
+| **XL** | 8+ | **Too large — break it down further** | — |
+
+If a task is L or larger, it should be broken into smaller tasks. An agent performs best on S and M tasks.
+
+**When to break a task down further:**
+- It would take more than one focused session (roughly 2+ hours of agent work)
+- You cannot describe the acceptance criteria in 3 or fewer bullet points
+- It touches two or more independent subsystems (e.g., auth and billing)
+- You find yourself writing "and" in the task title (a sign it is two tasks)
+
+## Output Files
+
+Save the plan as two files:
+
+- **`plan.md`** — design document: per-task description, dependencies, verify conditions. Stable after approval — not modified during execution.
+- **`todo.md`** — execution tracker: flat checklist. Agent ticks `[x]` after each task is done.
+
+## Plan Document Template
+
+**`plan.md`:**
+
+```markdown
+---
+id: "{slug}"
+slug: "{slug}"
+title: "{title} — Implementation Plan"
+features: ["{F-XXX}"]
+status: draft
+created: {YYYY-MM-DD}
+---
+
+## Summary
+
+[2-3 sentences on what will be implemented]
+
+## Tasks
+
+### Phase 1: [Phase name]
+
+#### T001 — [task title]
+
+[What this task delivers]
+
+**depends:** —
+**verify:** [verify condition or omit if no behavior]
+
+#### T002 — [task title]
+
+[What this task delivers]
+
+**depends:** T001
+**verify:** [AC-001] unit tests — [specific cases]
+
+### Phase N: Verification
+
+#### T00N — [integration test description]
+
+[End-to-end flow being tested]
+
+**depends:** T001, T002
+**verify:** integration tests pass — [happy path + error cases]
+
+## Definition of Done
+
+- [ ] [AC from spec — concise, preserve intent]
+- [ ] All unit tests pass
+- [ ] All integration tests pass
+```
+
+**`todo.md`:**
+
+```markdown
+# [title] — Todo
+
+### Phase 1: [Phase name]
+- [ ] T001 — [task title]
+- [ ] T002 — [task title]
+
+### Phase N: Verification
+- [ ] T00N — [integration test description]
+```
+
+## Parallelization Opportunities
+
+When multiple agents or sessions are available:
+
+- **Safe to parallelize:** Independent feature slices, tests for already-implemented features, documentation
+- **Must be sequential:** Database migrations, shared state changes, dependency chains
+- **Needs coordination:** Features that share an API contract (define the contract first, then parallelize)
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll figure it out as I go" | That's how you end up with a tangled mess and rework. 10 minutes of planning saves hours. |
+| "The tasks are obvious" | Write them down anyway. Explicit tasks surface hidden dependencies and forgotten edge cases. |
+| "Planning is overhead" | Planning is the task. Implementation without a plan is just typing. |
+| "I can hold it all in my head" | Context windows are finite. Written plans survive session boundaries and compaction. |
+
+## Red Flags
+
+- Starting implementation without a written task list
+- Tasks that say "implement the feature" without acceptance criteria
+- No verification steps in the plan
+- All tasks are XL-sized
+- No checkpoints between tasks
+- Dependency order isn't considered
+
+## Verification
+
+Before starting implementation, confirm:
+
+- [ ] Every task with behavior has a `verify:` field with specific test cases
+- [ ] Task dependencies are identified and ordered correctly
+- [ ] No task touches more than ~5 files
+- [ ] Final phase is Verification (integration/e2e tests)
+- [ ] todo.md is in sync with plan.md (same phases, same task IDs)
+- [ ] The human has reviewed and approved the plan

package/skills/scaffold/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: scaffold
+description: Khởi tạo project scaffold dựa trên sad.md — tạo plan.md và todo.md rồi thực thi theo plan. Chạy một lần duy nhất trước khi implement integration đầu tiên.
+---
+
+# scaffold
+
+## Overview
+
+Đọc `specs/main/sad.md`, phân rã thành plan.md và todo.md cho bước khởi tạo project, sau đó thực thi từng task theo thứ tự.
+
+Khác với `/spec-plan` — skill này không dừng lại sau khi sinh plan. Sau khi user confirm, nó execute luôn.
+
+## When to Use
+
+- Project chưa được khởi tạo
+- Muốn có một record rõ ràng về cách project được setup
+
+## When NOT to Use
+
+- `specs/main/sad.md` chưa có → chạy `/spec-sad` trước
+- Project đã được khởi tạo rồi → implement trực tiếp
+
+---
+
+## Process
+
+### Bước 1: Kiểm tra preconditions
+
+Đọc `specs/main/sad.md`:
+
+- **Không tồn tại hoặc là template** → dừng ngay:
+  > `sad.md` chưa có nội dung. Hãy chạy `/spec-sad` trước.
+
+- **Đã có nội dung** → tiếp tục.
+
+Kiểm tra `specs/integrations/000-scaffold/`:
+
+- **Không có plan.md và todo.md** → tiếp tục Bước 2 (sinh mới).
+
+- **Có plan.md nhưng không có todo.md** → hỏi:
+  > `plan.md` đã tồn tại nhưng thiếu `todo.md`. Ghi đè và chạy lại từ đầu?
+
+- **Có cả plan.md và todo.md** → đọc todo.md, đếm tasks:
+  - Nếu **tất cả tasks đã `[x]`** → thông báo:
+    > Scaffold đã hoàn thành ({N}/{N} tasks). Muốn chạy lại từ đầu?
+    - Nếu user muốn chạy lại → tiếp tục Bước 2.
+    - Nếu không → dừng.
+  - Nếu **có tasks chưa done** → hiển thị tiến độ:
+    ```
+    Scaffold đang ở giữa chừng ({done}/{total} tasks done):
+      ✓ T001 · {task title}
+      ✓ T002 · {task title}
+      ○ T003 · {task title}   ← chưa làm
+      ○ T004 · {task title}
+    
+    Tiếp tục từ T003?
+    ```
+    - Nếu user confirm → **nhảy thẳng đến Bước 6**, bắt đầu từ task đầu tiên chưa `[x]`.
+    - Nếu user muốn chạy lại → tiếp tục Bước 2.
+
+---
+
+### Bước 2: Load context từ sad.md
+
+Extract các thông tin cần thiết để sinh plan:
+
+- **Tech Stack** — từng layer và technology
+- **Infrastructure Overview** — môi trường, provider, deployment strategy
+- **Architectural Guardrails** — các constraints ảnh hưởng đến project setup
+
+Surface context và hỏi những gì sad.md không có:
+
+```
+TỪ SAD.MD TÔI HIỂU:
+- Framework: {tech stack}
+- Database: {tech stack}
+- Deploy: {infrastructure}
+- Guardrails liên quan đến scaffold: {list GUARD IDs}
+
+CẦN THÊM:
+1. Project name là gì?
+2. Package manager? (npm / pnpm / yarn) [default: npm]
+→ Sửa lại nếu sai trước khi tiếp tục.
+```
+
+Chỉ hỏi những gì thực sự không thể suy ra từ sad.md.
+
+---
+
+### Bước 3: Sinh plan.md và todo.md
+
+Phân rã scaffold thành tasks có thứ tự. Mỗi task phải:
+- Thực thi được bởi agent (chạy command hoặc tạo file)
+- Có verification rõ ràng trước khi mark done
+- Phụ thuộc đúng thứ tự
+
+**Dependency graph điển hình cho scaffold:**
+
+```
+    Verify (project chạy được)
+           │
+    Directory structure
+           │
+    Config & env vars ──── ORM init
+           │
+    Install dependencies
+           │
+    Initialize framework
+```
+
+**Phases điển hình** (điều chỉnh theo tech stack thực tế):
+
+- **Phase 1: Initialize** — khởi tạo project framework (create-next-app, create-vite, django-admin startproject, v.v.)
+- **Phase 2: Dependencies** — cài packages theo tech stack và guardrails
+- **Phase 3: Configuration** — init ORM, setup env file template, config files
+- **Phase 4: Directory Structure** — tạo thư mục theo layer architecture trong sad.md
+- **Phase 5: Verify** — project chạy được, kết nối DB thành công
+
+**Output format** (theo spec-plan convention):
+
+```markdown
+---
+id: "000-scaffold"
+slug: "000-scaffold"
+title: "Project Scaffold — Setup Plan"
+status: draft
+created: {YYYY-MM-DD}
+---
+
+## Summary
+
+{2-3 câu mô tả những gì sẽ được khởi tạo, dựa trên tech stack từ sad.md}
+
+## Dependency Graph
+
+{ASCII diagram — bottom = foundations, top = verify}
+
+## Tasks
+
+### Phase 1: Initialize
+
+#### T001 · {task title — starts with a verb}
+
+**Mục tiêu:** {One sentence: task này deliver gì}
+
+**depends:** —
+
+**Các bước:**
+1. {Command hoặc action cụ thể}
+2. {Command hoặc action cụ thể}
+
+**Verification:**
+- [ ] {Kết quả quan sát được sau khi task hoàn thành}
+
+---
+
+...
+
+### Phase N: Verify
+
+#### T00N · Verify scaffold hoạt động
+
+**Mục tiêu:** Xác nhận project chạy được và mọi connections hoạt động.
+
+**depends:** T001, T002, ...
+
+**Các bước:**
+1. Chạy dev server
+2. Verify kết nối database (nếu có)
+
+**Verification:**
+- [ ] Dev server start không lỗi
+- [ ] {DB connection verify nếu applicable}
+
+---
+
+## Definition of Done
+
+- [ ] Project khởi chạy thành công ở local
+- [ ] Tất cả dependencies đã được install
+- [ ] Directory structure khớp với architecture trong sad.md
+- [ ] Env template có đủ variables cần thiết
+```
+
+**todo.md format:**
+
+```markdown
+# Project Scaffold — Todo
+
+### Phase 1: Initialize
+- [ ] T001 · {task title}
+
+### Phase 2: Dependencies
+- [ ] T002 · {task title}
+
+...
+
+### Phase N: Verify
+- [ ] T00N · Verify scaffold hoạt động
+```
+
+Hiển thị draft cho user — **chưa ghi file**.
+
+---
+
+### Bước 4: Review — xác nhận với user
+
+> Draft trên đúng chưa? Confirm để ghi file và bắt đầu thực thi.
+
+Chỉ tiếp tục sau khi user confirm. Nếu cần chỉnh → cập nhật draft → hỏi lại.
+
+---
+
+### Bước 5: Ghi file
+
+Tạo thư mục `specs/integrations/000-scaffold/` nếu chưa có.
+
+Ghi:
+- `specs/integrations/000-scaffold/plan.md`
+- `specs/integrations/000-scaffold/todo.md`
+
+---
+
+### Bước 6: Thực thi plan
+
+Thực thi từng task theo thứ tự trong plan.md:
+
+```
+Bắt đầu thực thi scaffold...
+
+[T001] {task title}
+  → {action}
+  ✓ Verification passed
+  ✓ todo.md updated
+
+[T002] {task title}
+  → {action}
+  ✓ Verification passed
+  ✓ todo.md updated
+
+...
+```
+
+**Rules:**
+
+1. Thực thi đúng thứ tự — không skip task, không parallelize trừ khi `depends` cho phép
+2. Sau mỗi task: chạy verification steps trong `**Verification:**`
+3. Nếu verification pass → mark `[x]` trong todo.md → tiếp tục task tiếp theo
+4. Nếu verification fail → dừng ngay, báo lỗi cụ thể, không tiếp tục:
+
+```
+✗ T002 · {task title} — FAILED
+
+Lỗi: {error message}
+Bước đã thực thi: {bước số mấy}
+
+Cần xử lý thủ công trước khi tiếp tục.
+```
+
+5. Không tự ý bỏ qua lỗi hoặc retry quá 1 lần
+
+---
+
+### Bước 7: Hoàn thành
+
+Sau khi tất cả tasks pass:
+
+```
+✓ Scaffold hoàn thành
+
+  specs/integrations/000-scaffold/plan.md
+  specs/integrations/000-scaffold/todo.md
+
+Tất cả tasks: {N}/{N} ✓
+
+Bước tiếp theo:
+  - Điền các giá trị thực vào .env.local
+  {nếu có manual steps} - {manual step cần làm}
+  - /spec-new → bắt đầu integration đầu tiên
+```
+
+---
+
+## Verification
+
+Trước khi kết thúc, kiểm tra:
+
+- [ ] sad.md đã được đọc và tech stack được extract đúng
+- [ ] plan.md có Dependency Graph
+- [ ] Mỗi task có: Mục tiêu / depends / Các bước / Verification
+- [ ] todo.md đồng bộ với plan.md
+- [ ] User đã confirm plan trước khi execute
+- [ ] Mọi task verification pass trước khi mark done