spec-lite 1.0.0 → 1.0.2

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

@@ -1,13 +1,15 @@
 ---
 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.
+description: Strategy guide for breaking work into ordered, verifiable tasks — format-agnostic. Covers dependency mapping, vertical slicing, and task sizing. Invoked by wrapper skills (e.g. /plan) that own the output format; can also be used standalone.
 ---
 
 # 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.
+Strategy guide for decomposing work into small, verifiable tasks. This skill is **format-agnostic** — it defines *how to think* about breakdown (dependency mapping, slicing, sizing), not *how to write* the output. Output format is owned by the caller (e.g. `/plan` defines the exact markdown structure for SDD projects).
+
+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
 
@@ -39,15 +41,19 @@ Map what depends on what:
 ```
 Database schema
     │
-    ├── API models/types
-    │       │
-    │       ├── API endpoints
-    │       │       │
-    │       │       └── Frontend API client
-    │       │               │
-    │       │               └── UI components
+    ├── Domain models
     │       │
-    │       └── Validation logic
+    │       └── Services
+    │               │
+    │               ├── Validation logic
+    │               │
+    │               └── API endpoints
+    │                       │
+    │                       ├── Middleware
+    │                       │
+    │                       └── Frontend API client
+    │                               │
+    │                               └── UI components
     │
     └── Seed data / migrations
 ```
@@ -78,27 +84,23 @@ 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]
+Each task must capture:
 
-**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]
-```
+- **Title** — short, starts with a verb
+- **What it delivers** — one sentence or short paragraph
+- **Dependencies** — which tasks must complete first
+- **Verification conditions** — specific and testable (not just "tests pass")
 
-**`verify:` field rules:**
+**Verification rules:**
 
-| Task type | verify? | Example |
+| 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)* |
+| Has behavior (service, endpoint, validation) | Yes — specific unit tests | unit tests: valid input, missing field 400, duplicate 409 |
+| Pure infrastructure (migration, config) | Yes — smoke check | migration runs clean, rollback succeeds |
+| Task IS the test (Verification phase) | Yes — result | integration tests pass — happy path + error cases |
+| No behavior (docs, rename, comment) | No | *(omit)* |
 
-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.
+Rule: add verification 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. Reference AC IDs when the task covers specific criteria.
 
 ### Step 5: Order and Phases
 
@@ -139,78 +141,6 @@ If a task is L or larger, it should be broken into smaller tasks. An agent perfo
 - 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:
@@ -241,7 +171,7 @@ When multiple agents or sessions are available:
 
 Before starting implementation, confirm:
 
-- [ ] Every task with behavior has a `verify:` field with specific test cases
+- [ ] Every task with behavior has specific verification conditions (not just "tests pass")
 - [ ] Task dependencies are identified and ordered correctly
 - [ ] No task touches more than ~5 files
 - [ ] Final phase is Verification (integration/e2e tests)

package/skills/scaffold/SKILL.md

@@ -9,7 +9,7 @@ description: Khởi tạo project scaffold dựa trên sad.md — tạo plan.md
 
 Đọ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.
+Khác với `/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
 
@@ -117,7 +117,7 @@ Phân rã scaffold thành tasks có thứ tự. Mỗi task phải:
 - **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):
+**Output format** (theo plan convention):
 
 ```markdown
 ---

package/skills/spec-new/SKILL.md

@@ -70,11 +70,15 @@ Sections hiện có:
   [4] Scope (In Scope / Out of Scope)
   [5] Dependencies
   [A] All — viết lại toàn bộ từ đầu
+  [S] Lên spec từ frd.md hiện tại — frd.md đã đầy đủ, không cần chỉnh
 
-Chọn section cần cập nhật (có thể chọn nhiều, ví dụ: 2 3):
+Chọn (có thể chọn nhiều section, ví dụ: 2 3):
 ```
 
-Lưu lại lựa chọn section. Nếu chọn `A` → xử lý như tạo mới toàn bộ. Sau đó chuyển sang Bước 2.
+Lưu lại lựa chọn section.
+- Nếu chọn `A` → xử lý như tạo mới toàn bộ. Sau đó chuyển sang Bước 2.
+- Nếu chọn `S` → **bỏ qua Bước 3 (Interview)**. Dùng nội dung frd.md hiện tại làm input để sinh spec.md. Chuyển thẳng sang Bước 4.
+- Nếu chọn số section → cập nhật section đó. Sau đó chuyển sang Bước 2.
 
 ---
 

package/skills/spec-tech/SKILL.md

@@ -28,14 +28,22 @@ Tạo `tech.md` cho một integration trong `specs/integrations/{slug}/`.
 
 ### Bước 1: Xác định integration
 
-Quét thư mục `specs/integrations/`. Liệt kê **tất cả** integrations có `spec.md`, đánh dấu những cái đã có `tech.md`:
+**Nếu có ARGUMENT:**
+- Parse argument: có thể là số thứ tự (`2`, `002`) hoặc slug (`002-implement-todo`)
+- Quét `specs/integrations/*/spec.md`, tìm integration khớp với argument
+- Nếu không tìm thấy → báo lỗi:
+  > Không tìm thấy integration khớp với "{argument}". Kiểm tra lại tên hoặc số thứ tự.
+- Nếu tìm thấy → dùng integration đó, bắt đầu luôn
+
+**Nếu không có ARGUMENT:**
+
+Quét `specs/integrations/`. Liệt kê **tất cả** integrations có `spec.md`, đánh dấu những cái đã có `tech.md`:
 
 ```
 Integrations:
 
-  [1] f001-authentication       — User Authentication
-  [2] f003-app-browsing         — App Browsing & Opt-in         ✓ có tech.md
-  [3] f004-credit-system        — Credit System
+  [1] 001-implement-auth    — Implement Auth             spec✓ tech✓
+  [2] 002-implement-todo    — Implement Todo Management  spec✓ tech—
 
 Chọn số integration:
 ```
@@ -43,8 +51,6 @@ Chọn số integration:
 Nếu không có integration nào → thông báo:
 > Chưa có integration nào. Hãy chạy `/spec-new` trước.
 
-**Nếu có ARGUMENT** → đây là số thứ tự trong danh sách trên (ví dụ `1`, `2`, hoặc `001`). Parse thành số nguyên, bỏ qua leading zeros, map vào integration tương ứng — không cần hiển thị danh sách, chọn luôn.
-
 Nếu integration đã có `tech.md` → hỏi trước khi tiếp tục:
 > `tech.md` đã tồn tại cho integration này. Tiếp tục sẽ ghi đè. Tiếp tục không?
 
@@ -162,7 +168,7 @@ Thông báo kết quả:
 
 Bước tiếp theo:
   - Review và approve tech.md
-  - Implement theo tech.md
+  - /plan → tạo plan.md và todo.md cho integration này
   - Sau khi done: đổi status F-XXX trong prd.md thành DONE
   - Nếu Cascade Proposals có thay đổi → chạy /spec-domain hoặc /spec-sad
 ```

package/templates/integrations/plan-template.md

@@ -7,32 +7,81 @@ status: draft
 created: {YYYY-MM-DD}
 referenced_by:
   - conventions.md > 4. Integration Artifacts > 4.5 plan.md > Cấu trúc
-  - skills/spec-plan/SKILL.md > Output Format > plan.md
+  - skills/plan/SKILL.md > Output Format > plan.md
 ---
 
 ## Summary
 
 <!-- Mô tả ngắn những gì sẽ được implement trong integration này -->
 
+## Dependency Graph
+
+```
+<!-- ASCII diagram — bottom = foundations, top = UI. Ví dụ:
+
+Database schema
+    │
+    ├── Domain models
+    │       │
+    │       └── Services
+    │               │
+    │               └── API endpoints
+    │                       │
+    │                       └── UI components
+-->
+```
+
 ## Tasks
 
 ### Phase 1: {tên phase}
 
-- [ ] T001 — {mô tả task}
-- [ ] T002 — {mô tả task}
-- [ ] T003 — {mô tả task} (depends: T001)
+#### T001 · {task title — bắt đầu bằng động từ}
 
-### Phase 2: {tên phase}
+**Mục tiêu:** {One sentence: what this task delivers}
 
-- [ ] T004 — {mô tả task} (depends: T001, T002)
-- [ ] T005 — {mô tả task}
+**depends:** —
 
-<!-- Convention:
-  - ID tăng dần trong phạm vi integration: T001, T002...
-  - Dependency ghi rõ: (depends: T001, T003)
-  - Tasks trong cùng phase không có dependency → có thể xử lý song song
-  - Tasks across phases có dependency tuần tự
--->
+**Các bước:**
+1. {Concrete implementation step}
+2. {Concrete implementation step}
+
+**Verification:**
+- [ ] {specific test case hoặc observable result}
+
+---
+
+#### T002 · {task title}
+
+**Mục tiêu:** {One sentence}
+
+**depends:** T001
+
+**Các bước:**
+1. {Concrete implementation step}
+
+**Verification:**
+- [ ] {specific test case hoặc observable result}
+
+---
+
+### Phase N: Verification
+
+#### T00N · Integration tests — {flow name}
+
+**Mục tiêu:** {End-to-end flow being tested}
+
+**depends:** T001, T002, ...
+
+**Các bước:**
+1. {Test setup / seed data}
+2. {Execute happy path}
+3. {Execute error cases}
+
+**Verification:**
+- [ ] Happy path: {description}
+- [ ] Error case: {description}
+
+---
 
 ## Definition of Done
 

package/templates/integrations/spec-template.md

@@ -24,21 +24,27 @@ referenced_by:
 
 ### Feature: {feature-name}
 
-**Feature-level AC:**
+**Feature-level Acceptance Criteria:**
 
-- [ ] AC-F-001: GIVEN {precondition}
-               WHEN {action}
-               THEN {expected outcome}
+- [ ] AC-F-001
+  - **Given** {precondition}
+  - **When** {action}
+  - **Then** {expected outcome}
 
 <!-- Lặp lại block Story bên dưới cho mỗi user story thuộc feature này -->
 
-**Story: {story-title}**
+#### US-001: {Story title}
 
-> {mô tả user story — As a {role}, I want to {action} so that {benefit}}
+**{Persona}** muốn **{hành động}** để **{mục tiêu}**.
 
-- [ ] AC-S-001: GIVEN {precondition}
-               WHEN {action}
-               THEN {expected outcome}
+**Priority:** Must / Should / Could
+
+**Acceptance Criteria:**
+
+- [ ] AC-S-001
+  - **Given** {precondition}
+  - **When** {action}
+  - **Then** {expected outcome}
 
 ## Out of Scope
 

package/templates/integrations/todo-template.md

@@ -6,7 +6,7 @@ features: []
 created: {YYYY-MM-DD}
 referenced_by:
   - conventions.md > 4. Integration Artifacts > 4.6 todo.md > Cấu trúc
-  - skills/spec-plan/SKILL.md > Output Format > todo.md
+  - skills/plan/SKILL.md > Output Format > todo.md
 ---
 
 # {title} — Todo

package/templates/main/feature/frd-template.md

@@ -19,40 +19,44 @@ referenced_by:
 
 Criteria áp dụng cho toàn bộ feature — không gắn với story cụ thể (ví dụ: performance, security, accessibility).
 
-- [ ] GIVEN {precondition}
-      WHEN {action}
-      THEN {expected outcome}
+- [ ]
+  - **Given** {precondition}
+  - **When** {action}
+  - **Then** {expected outcome}
 
 ## User Stories
 
 ### US-001: {Story title}
 
-As a {persona}, I want to {action} so that {value}.
+**{Persona}** muốn **{hành động}** để **{mục tiêu}**.
 
 **Priority:** Must / Should / Could
 
 **Acceptance Criteria:**
 
-- [ ] GIVEN {precondition}
-      WHEN {action}
-      THEN {expected outcome}
-- [ ] GIVEN {precondition}
-      WHEN {action}
-      THEN {expected outcome}
+- [ ]
+  - **Given** {precondition}
+  - **When** {action}
+  - **Then** {expected outcome}
+- [ ]
+  - **Given** {precondition}
+  - **When** {action}
+  - **Then** {expected outcome}
 
 ---
 
 ### US-002: {Story title}
 
-As a {persona}, I want to {action} so that {value}.
+**{Persona}** muốn **{hành động}** để **{mục tiêu}**.
 
 **Priority:** Must / Should / Could
 
 **Acceptance Criteria:**
 
-- [ ] GIVEN {precondition}
-      WHEN {action}
-      THEN {expected outcome}
+- [ ]
+  - **Given** {precondition}
+  - **When** {action}
+  - **Then** {expected outcome}
 
 ---