spec-lite 1.0.0 → 1.0.2

package/skills/frontend-ui-engineering/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: frontend-ui-engineering
+description: Builds production-quality UIs. Use when building or modifying user-facing interfaces. Use when creating components, implementing layouts, managing state, or when the output needs to look and feel production-quality rather than AI-generated.
+---
+
+# Frontend UI Engineering
+
+## Overview
+
+Build production-quality user interfaces that are accessible, performant, and visually polished. The goal is UI that looks like it was built by a design-aware engineer at a top company — not like it was generated by an AI. This means real design system adherence, proper accessibility, thoughtful interaction patterns, and no generic "AI aesthetic."
+
+## When to Use
+
+- Building new UI components or pages
+- Modifying existing user-facing interfaces
+- Implementing responsive layouts
+- Adding interactivity or state management
+- Fixing visual or UX issues
+
+## Component Architecture
+
+### File Structure
+
+Colocate everything related to a component:
+
+```
+src/components/
+  TaskList/
+    TaskList.tsx          # Component implementation
+    TaskList.test.tsx     # Tests
+    TaskList.stories.tsx  # Storybook stories (if using)
+    use-task-list.ts      # Custom hook (if complex state)
+    types.ts              # Component-specific types (if needed)
+```
+
+### Component Patterns
+
+**Prefer composition over configuration:**
+
+```tsx
+// Good: Composable
+<Card>
+  <CardHeader>
+    <CardTitle>Tasks</CardTitle>
+  </CardHeader>
+  <CardBody>
+    <TaskList tasks={tasks} />
+  </CardBody>
+</Card>
+
+// Avoid: Over-configured
+<Card
+  title="Tasks"
+  headerVariant="large"
+  bodyPadding="md"
+  content={<TaskList tasks={tasks} />}
+/>
+```
+
+**Keep components focused:**
+
+```tsx
+// Good: Does one thing
+export function TaskItem({ task, onToggle, onDelete }: TaskItemProps) {
+  return (
+    <li className="flex items-center gap-3 p-3">
+      <Checkbox checked={task.done} onChange={() => onToggle(task.id)} />
+      <span className={task.done ? 'line-through text-muted' : ''}>{task.title}</span>
+      <Button variant="ghost" size="sm" onClick={() => onDelete(task.id)}>
+        <TrashIcon />
+      </Button>
+    </li>
+  );
+}
+```
+
+**Separate data fetching from presentation:**
+
+```tsx
+// Container: handles data
+export function TaskListContainer() {
+  const { tasks, isLoading, error } = useTasks();
+
+  if (isLoading) return <TaskListSkeleton />;
+  if (error) return <ErrorState message="Failed to load tasks" retry={refetch} />;
+  if (tasks.length === 0) return <EmptyState message="No tasks yet" />;
+
+  return <TaskList tasks={tasks} />;
+}
+
+// Presentation: handles rendering
+export function TaskList({ tasks }: { tasks: Task[] }) {
+  return (
+    <ul role="list" className="divide-y">
+      {tasks.map(task => <TaskItem key={task.id} task={task} />)}
+    </ul>
+  );
+}
+```
+
+## State Management
+
+**Choose the simplest approach that works:**
+
+```
+Local state (useState)           → Component-specific UI state
+Lifted state                     → Shared between 2-3 sibling components
+Context                          → Theme, auth, locale (read-heavy, write-rare)
+URL state (searchParams)         → Filters, pagination, shareable UI state
+Server state (React Query, SWR)  → Remote data with caching
+Global store (Zustand, Redux)    → Complex client state shared app-wide
+```
+
+**Avoid prop drilling deeper than 3 levels.** If you're passing props through components that don't use them, introduce context or restructure the component tree.
+
+## Design System Adherence
+
+### Avoid the AI Aesthetic
+
+AI-generated UI has recognizable patterns. Avoid all of them:
+
+| AI Default | Why It Is a Problem | Production Quality |
+|---|---|---|
+| Purple/indigo everything | Models default to visually "safe" palettes, making every app look identical | Use the project's actual color palette |
+| Excessive gradients | Gradients add visual noise and clash with most design systems | Flat or subtle gradients matching the design system |
+| Rounded everything (rounded-2xl) | Maximum rounding signals "friendly" but ignores the hierarchy of corner radii in real designs | Consistent border-radius from the design system |
+| Generic hero sections | Template-driven layout with no connection to the actual content or user need | Content-first layouts |
+| Lorem ipsum-style copy | Placeholder text hides layout problems that real content reveals (length, wrapping, overflow) | Realistic placeholder content |
+| Oversized padding everywhere | Equal generous padding destroys visual hierarchy and wastes screen space | Consistent spacing scale |
+| Stock card grids | Uniform grids are a layout shortcut that ignores information priority and scanning patterns | Purpose-driven layouts |
+| Shadow-heavy design | Layered shadows add depth that competes with content and slows rendering on low-end devices | Subtle or no shadows unless the design system specifies |
+
+### Spacing and Layout
+
+Use a consistent spacing scale. Don't invent values:
+
+```css
+/* Use the scale: 0.25rem increments (or whatever the project uses) */
+/* Good */  padding: 1rem;      /* 16px */
+/* Good */  gap: 0.75rem;       /* 12px */
+/* Bad */   padding: 13px;      /* Not on any scale */
+/* Bad */   margin-top: 2.3rem; /* Not on any scale */
+```
+
+### Typography
+
+Respect the type hierarchy:
+
+```
+h1 → Page title (one per page)
+h2 → Section title
+h3 → Subsection title
+body → Default text
+small → Secondary/helper text
+```
+
+Don't skip heading levels. Don't use heading styles for non-heading content.
+
+### Color
+
+- Use semantic color tokens: `text-primary`, `bg-surface`, `border-default` — not raw hex values
+- Ensure sufficient contrast (4.5:1 for normal text, 3:1 for large text)
+- Don't rely solely on color to convey information (use icons, text, or patterns too)
+
+## Accessibility (WCAG 2.1 AA)
+
+Every component must meet these standards:
+
+### Keyboard Navigation
+
+```tsx
+// Every interactive element must be keyboard accessible
+<button onClick={handleClick}>Click me</button>        // ✓ Focusable by default
+<div onClick={handleClick}>Click me</div>               // ✗ Not focusable
+<div role="button" tabIndex={0} onClick={handleClick}    // ✓ But prefer <button>
+     onKeyDown={e => {
+       if (e.key === 'Enter') handleClick();
+       if (e.key === ' ') e.preventDefault();
+     }}
+     onKeyUp={e => {
+       if (e.key === ' ') handleClick();
+     }}>
+  Click me
+</div>
+```
+
+### ARIA Labels
+
+```tsx
+// Label interactive elements that lack visible text
+<button aria-label="Close dialog"><XIcon /></button>
+
+// Label form inputs
+<label htmlFor="email">Email</label>
+<input id="email" type="email" />
+
+// Or use aria-label when no visible label exists
+<input aria-label="Search tasks" type="search" />
+```
+
+### Focus Management
+
+```tsx
+// Move focus when content changes
+function Dialog({ isOpen, onClose }: DialogProps) {
+  const closeRef = useRef<HTMLButtonElement>(null);
+
+  useEffect(() => {
+    if (isOpen) closeRef.current?.focus();
+  }, [isOpen]);
+
+  // Trap focus inside dialog when open
+  return (
+    <dialog open={isOpen}>
+      <button ref={closeRef} onClick={onClose}>Close</button>
+      {/* dialog content */}
+    </dialog>
+  );
+}
+```
+
+### Meaningful Empty and Error States
+
+```tsx
+// Don't show blank screens
+function TaskList({ tasks }: { tasks: Task[] }) {
+  if (tasks.length === 0) {
+    return (
+      <div role="status" className="text-center py-12">
+        <TasksEmptyIcon className="mx-auto h-12 w-12 text-muted" />
+        <h3 className="mt-2 text-sm font-medium">No tasks</h3>
+        <p className="mt-1 text-sm text-muted">Get started by creating a new task.</p>
+        <Button className="mt-4" onClick={onCreateTask}>Create Task</Button>
+      </div>
+    );
+  }
+
+  return <ul role="list">...</ul>;
+}
+```
+
+## Responsive Design
+
+Design for mobile first, then expand:
+
+```tsx
+// Tailwind: mobile-first responsive
+<div className="
+  grid grid-cols-1      /* Mobile: single column */
+  sm:grid-cols-2        /* Small: 2 columns */
+  lg:grid-cols-3        /* Large: 3 columns */
+  gap-4
+">
+```
+
+Test at these breakpoints: 320px, 768px, 1024px, 1440px.
+
+## Loading and Transitions
+
+```tsx
+// Skeleton loading (not spinners for content)
+function TaskListSkeleton() {
+  return (
+    <div className="space-y-3" aria-busy="true" aria-label="Loading tasks">
+      {Array.from({ length: 3 }).map((_, i) => (
+        <div key={i} className="h-12 bg-muted animate-pulse rounded" />
+      ))}
+    </div>
+  );
+}
+
+// Optimistic updates for perceived speed
+function useToggleTask() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: toggleTask,
+    onMutate: async (taskId) => {
+      await queryClient.cancelQueries({ queryKey: ['tasks'] });
+      const previous = queryClient.getQueryData(['tasks']);
+
+      queryClient.setQueryData(['tasks'], (old: Task[]) =>
+        old.map(t => t.id === taskId ? { ...t, done: !t.done } : t)
+      );
+
+      return { previous };
+    },
+    onError: (_err, _taskId, context) => {
+      queryClient.setQueryData(['tasks'], context?.previous);
+    },
+  });
+}
+```
+
+## See Also
+
+For detailed accessibility requirements and testing tools, see `references/accessibility-checklist.md`.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "Accessibility is a nice-to-have" | It's a legal requirement in many jurisdictions and an engineering quality standard. |
+| "We'll make it responsive later" | Retrofitting responsive design is 3x harder than building it from the start. |
+| "The design isn't final, so I'll skip styling" | Use the design system defaults. Unstyled UI creates a broken first impression for reviewers. |
+| "This is just a prototype" | Prototypes become production code. Build the foundation right. |
+| "The AI aesthetic is fine for now" | It signals low quality. Use the project's actual design system from the start. |
+
+## Red Flags
+
+- Components with more than 200 lines (split them)
+- Inline styles or arbitrary pixel values
+- Missing error states, loading states, or empty states
+- No keyboard navigation testing
+- Color as the sole indicator of state (red/green without text or icons)
+- Generic "AI look" (purple gradients, oversized cards, stock layouts)
+
+## Verification
+
+After building UI:
+
+- [ ] Component renders without console errors
+- [ ] All interactive elements are keyboard accessible (Tab through the page)
+- [ ] Screen reader can convey the page's content and structure
+- [ ] Responsive: works at 320px, 768px, 1024px, 1440px
+- [ ] Loading, error, and empty states all handled
+- [ ] Follows the project's design system (spacing, colors, typography)
+- [ ] No accessibility warnings in dev tools or axe-core

package/skills/incremental-implementation/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: incremental-implementation
+description: Delivers changes incrementally. Use when implementing any feature or change that touches more than one file. Use when you're about to write a large amount of code at once, or when a task feels too big to land in one step.
+---
+
+# Incremental Implementation
+
+## Overview
+
+Build in thin vertical slices — implement one piece, test it, verify it, then expand. Avoid implementing an entire feature in one pass. Each increment should leave the system in a working, testable state. This is the execution discipline that makes large features manageable.
+
+## When to Use
+
+- Implementing any multi-file change
+- Building a new feature from a task breakdown
+- Refactoring existing code
+- Any time you're tempted to write more than ~100 lines before testing
+
+**When NOT to use:** Single-file, single-function changes where the scope is already minimal.
+
+## The Increment Cycle
+
+```
+┌──────────────────────────────────────┐
+│                                      │
+│   Implement ──→ Test ──→ Verify ──┐  │
+│       ▲                           │  │
+│       └───── Commit ◄─────────────┘  │
+│              │                       │
+│              ▼                       │
+│          Next slice                  │
+│                                      │
+└──────────────────────────────────────┘
+```
+
+For each slice:
+
+1. **Implement** the smallest complete piece of functionality
+2. **Test** — run the test suite (or write a test if none exists)
+3. **Verify** — confirm the slice works as expected (tests pass, build succeeds, manual check)
+4. **Commit** -- save your progress with a descriptive message (see `git-workflow-and-versioning` for atomic commit guidance)
+5. **Move to the next slice** — carry forward, don't restart
+
+## Slicing Strategies
+
+### Vertical Slices (Preferred)
+
+Build one complete path through the stack:
+
+```
+Slice 1: Create a task (DB + API + basic UI)
+    → Tests pass, user can create a task via the UI
+
+Slice 2: List tasks (query + API + UI)
+    → Tests pass, user can see their tasks
+
+Slice 3: Edit a task (update + API + UI)
+    → Tests pass, user can modify tasks
+
+Slice 4: Delete a task (delete + API + UI + confirmation)
+    → Tests pass, full CRUD complete
+```
+
+Each slice delivers working end-to-end functionality.
+
+### Contract-First Slicing
+
+When backend and frontend need to develop in parallel:
+
+```
+Slice 0: Define the API contract (types, interfaces, OpenAPI spec)
+Slice 1a: Implement backend against the contract + API tests
+Slice 1b: Implement frontend against mock data matching the contract
+Slice 2: Integrate and test end-to-end
+```
+
+### Risk-First Slicing
+
+Tackle the riskiest or most uncertain piece first:
+
+```
+Slice 1: Prove the WebSocket connection works (highest risk)
+Slice 2: Build real-time task updates on the proven connection
+Slice 3: Add offline support and reconnection
+```
+
+If Slice 1 fails, you discover it before investing in Slices 2 and 3.
+
+## Implementation Rules
+
+### Rule 0: Simplicity First
+
+Before writing any code, ask: "What is the simplest thing that could work?"
+
+After writing code, review it against these checks:
+- Can this be done in fewer lines?
+- Are these abstractions earning their complexity?
+- Would a staff engineer look at this and say "why didn't you just..."?
+- Am I building for hypothetical future requirements, or the current task?
+
+```
+SIMPLICITY CHECK:
+✗ Generic EventBus with middleware pipeline for one notification
+✓ Simple function call
+
+✗ Abstract factory pattern for two similar components
+✓ Two straightforward components with shared utilities
+
+✗ Config-driven form builder for three forms
+✓ Three form components
+```
+
+Three similar lines of code is better than a premature abstraction. Implement the naive, obviously-correct version first. Optimize only after correctness is proven with tests.
+
+### Rule 0.5: Scope Discipline
+
+Touch only what the task requires.
+
+Do NOT:
+- "Clean up" code adjacent to your change
+- Refactor imports in files you're not modifying
+- Remove comments you don't fully understand
+- Add features not in the spec because they "seem useful"
+- Modernize syntax in files you're only reading
+
+If you notice something worth improving outside your task scope, note it — don't fix it:
+
+```
+NOTICED BUT NOT TOUCHING:
+- src/utils/format.ts has an unused import (unrelated to this task)
+- The auth middleware could use better error messages (separate task)
+→ Want me to create tasks for these?
+```
+
+### Rule 1: One Thing at a Time
+
+Each increment changes one logical thing. Don't mix concerns:
+
+**Bad:** One commit that adds a new component, refactors an existing one, and updates the build config.
+
+**Good:** Three separate commits — one for each change.
+
+### Rule 2: Keep It Compilable
+
+After each increment, the project must build and existing tests must pass. Don't leave the codebase in a broken state between slices.
+
+### Rule 3: Feature Flags for Incomplete Features
+
+If a feature isn't ready for users but you need to merge increments:
+
+```typescript
+// Feature flag for work-in-progress
+const ENABLE_TASK_SHARING = process.env.FEATURE_TASK_SHARING === 'true';
+
+if (ENABLE_TASK_SHARING) {
+  // New sharing UI
+}
+```
+
+This lets you merge small increments to the main branch without exposing incomplete work.
+
+### Rule 4: Safe Defaults
+
+New code should default to safe, conservative behavior:
+
+```typescript
+// Safe: disabled by default, opt-in
+export function createTask(data: TaskInput, options?: { notify?: boolean }) {
+  const shouldNotify = options?.notify ?? false;
+  // ...
+}
+```
+
+### Rule 5: Rollback-Friendly
+
+Each increment should be independently revertable:
+
+- Additive changes (new files, new functions) are easy to revert
+- Modifications to existing code should be minimal and focused
+- Database migrations should have corresponding rollback migrations
+- Avoid deleting something in one commit and replacing it in the same commit — separate them
+
+## Working with Agents
+
+When directing an agent to implement incrementally:
+
+```
+"Let's implement Task 3 from the plan.
+
+Start with just the database schema change and the API endpoint.
+Don't touch the UI yet — we'll do that in the next increment.
+
+After implementing, run `npm test` and `npm run build` to verify
+nothing is broken."
+```
+
+Be explicit about what's in scope and what's NOT in scope for each increment.
+
+## Increment Checklist
+
+After each increment, verify:
+
+- [ ] The change does one thing and does it completely
+- [ ] All existing tests still pass (`npm test`)
+- [ ] The build succeeds (`npm run build`)
+- [ ] Type checking passes (`npx tsc --noEmit`)
+- [ ] Linting passes (`npm run lint`)
+- [ ] The new functionality works as expected
+- [ ] The change is committed with a descriptive message
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "I'll test it all at the end" | Bugs compound. A bug in Slice 1 makes Slices 2-5 wrong. Test each slice. |
+| "It's faster to do it all at once" | It *feels* faster until something breaks and you can't find which of 500 changed lines caused it. |
+| "These changes are too small to commit separately" | Small commits are free. Large commits hide bugs and make rollbacks painful. |
+| "I'll add the feature flag later" | If the feature isn't complete, it shouldn't be user-visible. Add the flag now. |
+| "This refactor is small enough to include" | Refactors mixed with features make both harder to review and debug. Separate them. |
+
+## Red Flags
+
+- More than 100 lines of code written without running tests
+- Multiple unrelated changes in a single increment
+- "Let me just quickly add this too" scope expansion
+- Skipping the test/verify step to move faster
+- Build or tests broken between increments
+- Large uncommitted changes accumulating
+- Building abstractions before the third use case demands it
+- Touching files outside the task scope "while I'm here"
+- Creating new utility files for one-time operations
+
+## Verification
+
+After completing all increments for a task:
+
+- [ ] Each increment was individually tested and committed
+- [ ] The full test suite passes
+- [ ] The build is clean
+- [ ] The feature works end-to-end as specified
+- [ ] No uncommitted changes remain

package/skills/{spec-plan → plan}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: spec-plan
+name: plan
 description: Tạo plan.md và todo.md cho một integration — phân rã tasks từ spec.md và tech.md. SDD wrapper quanh planning-and-task-breakdown — chỉ làm context loading, delegate toàn bộ breakdown cho planning-and-task-breakdown.
 ---
 
-# spec-plan
+# plan
 
 ## Overview
 
@@ -27,22 +27,28 @@ Mọi quyết định về sizing, slicing đều thuộc về `planning-and-tas
 
 ### Bước 1: Xác định integration
 
+**Nếu có ARGUMENT:**
+- Parse argument: có thể là số thứ tự (`2`, `002`) hoặc slug (`002-implement-todo`)
+- Quét `specs/integrations/*/`, 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:
 
 ```
 Integrations:
 
-  [1] f001-authentication       — User Authentication        spec✓ tech✓  plan—
-  [2] f003-app-browsing         — App Browsing & Opt-in      spec✓ tech—
-  [3] f004-credit-system        — Credit System              spec—
+  [1] 001-implement-auth    — Implement Auth             spec✓ tech✓ plan✓
+  [2] 002-implement-todo    — Implement Todo Management  spec✓ tech✓ plan—
 
 Chọn số integration:
 ```
 
 Legend: `✓` = có, `—` = chưa có
 
-Nếu có ARGUMENT → chọn luôn, không hiển thị danh sách.
-
 Nếu plan.md / todo.md đã tồn tại → hỏi trước khi ghi đè.
 
 ---
@@ -84,77 +90,7 @@ Invoke `planning-and-task-breakdown` với context đã load. Skill đó sẽ th
 
 ### 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]
-
-## Dependency Graph
-
-[ASCII diagram — bottom = foundations, top = UI. Ví dụ:]
-
-    UI Components
-         │
-    API Routes ──── Middleware
-         │
-      Services
-         │
-    Prisma Schema
-
-## Tasks
-
-### Phase 1: [Phase name]
-
-#### T001 · [task title — starts with a verb]
-
-**Mục tiêu:** [One sentence: what this task delivers]
-
-**depends:** — (hoặc T-IDs)
-
-**Các bước:**
-1. [Concrete implementation step]
-2. [Concrete implementation step]
-
-**Verification:**
-- [ ] [AC-F-001] [specific test case]
-- [ ] [smoke check or 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
-
-- [ ] [AC-F-001 / AC-S-001] [AC description — concise, preserve intent]
-- [ ] All unit tests pass
-- [ ] All integration tests pass
-```
+Dùng `.claude/templates/integrations/plan-template.md` làm skeleton, điền nội dung từ breakdown vào từng section.
 
 **Lưu ý format:**
 - Task ID dùng `·` (middle dot), không dùng `—`
@@ -164,16 +100,7 @@ created: {YYYY-MM-DD}
 
 ### todo.md
 
-```markdown
-# [title] — Todo
-
-### Phase 1: [Phase name]
-- [ ] T001 · [task title]
-- [ ] T002 · [task title]
-
-### Phase N: Verification
-- [ ] T00N · Integration tests — [flow name]
-```
+Dùng `.claude/templates/integrations/todo-template.md` làm skeleton, điền nội dung từ breakdown vào từng section.
 
 ---