Imported from jangtrinh/EaseUI-Agent (.claude/skills/feature-dev/SKILL.md). Install upstream with npx skills add jangtrinh/EaseUI-Agent --skill feature-dev. Copyright stays with the author.

EaseUI Feature Development Workflow

5-phase pipeline modeled after Amazon, Basecamp, Stripe, and Linear. Each phase produces a specific artifact, loads the right skills, and requires approval before advancing.

Pipeline: Triage → Brainstorm → Plan → Document → Dev

Entry at any phase: If earlier artifacts already exist, start at the next phase.

Auto-Start (EVERY conversation)

// turbo

brv query "{feature} EaseUI architecture"

Phase 0: TRIAGE → Route to correct workflow

Trigger: Every feature request. Run BEFORE any other phase. Before starting ANY phase, categorize the task:

Sprint Mode (XS tasks)

1. Create task.md with 3-5 checklist items
2. Code → verify in browser → commit
3. brv curate at end
4. NO brainstorm.md, usecases.md, or blueprint.md required

Self-check: "Would a Press Release for this feature make sense?" If no → Sprint Mode. If yes → Full pipeline.

Phase 1: BRAINSTORM → brainstorm.md

Trigger: "brainstorm [feature]", "ideate", "explore", "shape" Output: plans/specs/{feature-id}/brainstorm.md Gate: User approves brainstorm before advancing to Phase 2.

Fast-Track: Visual Reference Provided

If user provides a visual reference (HTML, screenshot, Figma link, or design mockup):

1. Extract the implicit spec from the reference (colors, layout, components, interactions)
2. Document as a lightweight brainstorm.md with:
   • Reference source link/description
   • Key design decisions extracted
   • Anything MISSING from the reference that needs clarification
3. Skip Press Release, User Stories, MoSCoW
4. Proceed to Phase 3 or 4 directly (user approval = implicit from providing the reference)

Rationale: A pixel-perfect reference IS the brainstorm output. Forcing Amazon-style Press Releases for "match this design" tasks is theater.

Load Context First

// turbo

brv query "{feature} EaseUI architecture"

• Read prompt-engineer/SKILL.md — optimize the problem framing
• Read easeui-docs/SKILL.md → check docs/*/README.md for any related existing features

Actions

1. Press Release (Amazon): 1-2 paragraph hypothetical announcement. What problem is solved? Why should users be excited?

2. User Stories: "As a [Persona], I want to [Action], so that [Benefit]."

3. MoSCoW Prioritization: Must (P0) / Should (P1) / Could (P2) / Won't (backlog).

4. Appetite & No-Gos (Basecamp): Time budget + rabbit holes we will NOT build.

5. World-Class Research Protocol (replaces Deep-Thinking + Prior Art):

   Source: Lucius neural propagation theory — hướng loang ban đầu quyết định chất lượng. Mục tiêu: Đảm bảo AI research GỐC RỄ, không chỉ bề mặt.

   Step	Action	Output
   ① Benchmark	Ai giải quyết vấn đề này tốt nhất? Tìm đỉnh (Figma, Linear, Stripe, v0...), không tìm trung bình	Best-in-class examples + cách họ giải quyết
   ② First Principles	Bóc hết triệu chứng. Vấn đề GỐC RỄ là gì? World-class giải quyết gốc, không giải quyết bề mặt	Root problem statement (1 câu)
   ③ Proven Frameworks	Mô hình tư duy / phương pháp luận đã thành công ở quy mô lớn? (McKinsey, Toyota, YC... tùy lĩnh vực)	Framework áp dụng + lý do chọn
   ④ Cross-Domain	Ý tưởng xuất sắc thường đến từ ngành khác. Tìm giải pháp "chuyển dịch" từ lĩnh vực bên ngoài	1+ cross-domain insight
   ⑤ Trade-offs	Không có giải pháp hoàn hảo. Đang đánh đổi cái gì? Lựa chọn có chủ đích	Trade-off table (chọn X, mất Y, chấp nhận vì Z)
   ⑥ Executability	Giải pháp brilliant mà không thực thi được = vô nghĩa. Điều chỉnh cho phù hợp nguồn lực, ràng buộc	Adjusted solution + constraints acknowledged

Anti-Patterns

• ❌ Don't jump to solutions — define the problem first (First Principles)
• ❌ Don't skip No-Gos — scope creep kills projects
• ❌ Don't brainstorm in a vacuum — query ByteRover for existing patterns
• ❌ Don't benchmark averages — find the BEST in the world, not the industry norm
• ❌ Don't ignore cross-domain — the best solution often comes from outside your field

Phase 2: PLAN → usecases.md

Trigger: "plan [feature]", "use cases", "define requirements" Prerequisite: brainstorm.md must exist. If not, run Phase 1 first. Output: plans/specs/{feature-id}/usecases.md Gate: User approves use cases before advancing to Phase 3.

Load Skills

• Read product-designer/SKILL.md — apply UX Psychology (Hick's Law for navigation, Fitts' for CTAs, Miller's for grouping)
• Read easeui-core-components/SKILL.md — know what tokens, components, and animations already exist
• Read product-designer/ux-psychology.md — ground every decision in a UX law

Actions

1. Use Cases: Define each UC with ID, title, actor, precondition, happy path, and edge cases.
2. Acceptance Criteria (Gherkin): For each Must UC: Given [Context] → When [Action] → Then [Outcome].
3. Edge Cases & Error States: Network drops, empty states, permissions denied, rate limits.
4. UX Decisions Table: Map every major decision to a UX law or Gestalt principle.
5. Design System Check: List which existing tokens/components from easeui-core-components apply. Flag any new tokens needed.
6. Appetite Check (Shape Up): For each UC, estimate effort vs value. Defer low-ROI items before Phase 3 specs them.

   | UC | Effort | Value | Ship this cycle? |
   |----|--------|-------|------------------|
   | UC-08 | High (cross-cutting) | Low (AI-only) | ❌ Defer |
   

Anti-Patterns

• ❌ Don't plan only the happy path — the sad path IS the product quality
• ❌ Don't ignore existing components — check component-catalog.ts first
• ❌ "It looks nice" is never sufficient rationale — cite a UX law
• ❌ Don't spec UCs you know will be deferred — mark them in Appetite Check first

Phase 3: DOCUMENT → blueprint.md + STATUS.md

Trigger: "document [feature]", "spec [feature]", "blueprint", "tech spec" Prerequisite: usecases.md must exist. If not, run Phase 2 first. Output: plans/specs/{feature-id}/blueprint.md + STATUS.md (created/updated) Gate: User approves blueprint before advancing to Phase 4.

Load Skills

• Read product-designer/SKILL.md — apply UX psychology and spatial layout thinking for ASCII wireframes
• Read easeui-docs/SKILL.md → read docs/*/README.md for the feature area being modified
• Read easeui-core-components/SKILL.md — specify exact tokens (var(--green), .btn-primary, .streaming-border)
• Read dev-rules.md workflow — coding standards for file structure, naming, TypeScript patterns
• If feature has animations/micro-interactions: Read motionwind/SKILL.md — specify animation classes in blueprint
• Reference plans/templates/feature-implementation-template.md for spec structure

Actions

1. Information Architecture: Page/component hierarchy, navigation flow.
2. ASCII Wireframes (MANDATORY for UI changes): For every UC that adds or modifies UI, include an ASCII wireframe showing spatial layout, element placement, and interaction states. This is the single highest-value artifact for AI implementation fidelity.

   Example format:
   ┌─────────────────────────────────┐
   │  [🔍 Search...]  [Filter] [Sort]│
   │  ┌──────┐  ┌──────┐  ┌──────┐  │
   │  │ Card │  │ Card │  │ Card │  │
   │  └──────┘  └──────┘  └──────┘  │
   └─────────────────────────────────┘
   

   Why: AI tokenizes ASCII losslessly (~50 tokens) vs images (~1000+ tokens, lossy). ASCII wireframes are git-diffable, survive context truncation, and map directly to Tailwind layout classes.
3. File Structure: [NEW] and [MOD] files with full paths.
4. 🔴 Clean-Code File Audit (MANDATORY): Before finalizing any [NEW] file, run the Component Reuse Protocol:

   For each [NEW] lib/utility file:
     1. tilth_search("keyword") --scope app/src/lib  (or: tilth_files "*keyword*" --scope app/src/lib)
     2. If similar file exists → change to [MOD] and extend it
     3. If file has only 1 exported function → inline where used (no single-function files)
   
   For each [NEW] component file:
     1. Check easeui-core-components registry
     2. tilth_search("keyword") --scope app/src/components  (or: tilth_files "*keyword*" --scope app/src/components)
     3. If similar exists → reuse or extend. Only create new if confirmed absent.
   

   Why this gate: Without it, blueprints accumulate unnecessary new files that duplicate existing utilities. Caught in practice: color-scale-generator.ts when color-scales.ts already existed; color-contrast.ts when color-utils.ts already existed.

5. Component API Contracts: TypeScript interfaces, props, return types.
6. State Management: Zustand store slices, actions, selectors.
7. Design Token Mapping: Exact tokens from easeui-core-components for every visual element.
8. Data Contracts: Table aligning every shared field across all data sources. Prevents format mismatches.

   | Field | Source | Format | Example |
   |-------|--------|--------|---------|
   | phase | README.md | `P{n}` | `"P1"` |
   | phase | STATUS.md | `P{n}` (normalized) | `"P0"` |
   | status | STATUS.md | kebab-case enum | `"in-progress"` |
   

9. Accessibility Plan: WCAG requirements, keyboard nav, screen reader behavior.
10. Create/Update STATUS.md: YAML frontmatter (status: specced), UC checklist, key files table.

Anti-Patterns

• ❌ Don't invent new design tokens — use what exists in easeui-core-components
• ❌ Don't write vague specs ("make it look good") — specify exact classes, shadows, radii
• ❌ Don't skip STATUS.md — PM Hub reads it directly
• ❌ Don't skip ASCII wireframes for UI changes — they are the #1 source of implementation accuracy
• ❌ Don't skip Clean-Code File Audit — creating new files without checking existing ones causes code duplication

Phase 4: DEV → Source Code

Trigger: "build [feature]", "implement", "develop", "code" Prerequisite: blueprint.md must exist. If not, run Phase 3 first. Output: Working source code, verified and synced.

Load Skills

• Read design.md workflow — full design orchestrator
• Read easeui-core-components/SKILL.md — build with real tokens
• Read dap-debugging/SKILL.md — interactive debugger for runtime issues
• Read react-best-practices/SKILL.md — React/Next.js performance: waterfalls, bundle size, rerenders
• If feature has animations: Read motionwind/SKILL.md + grep motionwind/data/patterns.csv for ready-made patterns
• If building reusable components: Read storybook/SKILL.md — CSF3 stories, interaction testing, portable stories
• Grep CSVs in easeui-core-components/data/ for relevant patterns (UX guidelines, React performance, Next.js, accessibility)

Define Scope (MANDATORY before coding)

1. List exactly what WILL ship in task.md (numbered DoD):

   DoD:
   1. Light theme code panel
   2. Tab switcher (HTML/CSS/JS)
   3. Footer with metadata
   

2. List what is OUT OF SCOPE
3. When user adds scope mid-task, update DoD and acknowledge:

   "✚ Adding custom search panel to DoD (now 4 items, was 3)"

Execute (Linear Method)

1. Atomic Tasks: Break into clear, non-verbose items in task.md.
2. Fixed Time, Variable Scope (Shape Up): If stuck, cut scope to hit the primary objective.
3. Code strictly per the approved blueprint. Every color uses var(--*), every shadow uses var(--shadow-*).
4. Code Navigation: Use tilth_search for finding definitions and tracing call chains. Use tilth_read for reading files (auto-outlines large files). Avoid raw grep/cat — see GEMINI.md tool mapping.

Debug Protocol (when bugs arise during dev)

Rule: Print-debugging is the LAST resort. Use dap first.

Confidence Protocol

Before advancing each gate, rate confidence 0-100%:

❌ Anti-pattern: Never ask open-ended "What should I do?" — always present binary choices with a recommendation.

Verify (Stripe Quality Bar)

4. Run Lite Gate after each commit — tsc --noEmit + browser screenshot + token check (see /review-gate).
5. Run Full /review-gate only before merge PR (M/L tasks) — 4 AI passes + 4 breakpoints.
6. Smoke Test Matrix: Auto-generate from Gherkin acceptance criteria — one checkbox per UC's core assertion.

   - [ ] UC-05: Click P1 chip → only P1 features visible
   - [ ] UC-06: Sort by priority → P1 cards appear first
   - [ ] UC-07: Malform STATUS.md → ⚠️ badge on card
   

7. Run 10-Point Design Audit (creative gate) — must score ≥ 8/10.
8. Test at breakpoints: 375px, 768px, 1024px, 1440px.

Auto-Fix Retry (Gates 2, 4, 5 only)

If a gate fails:

1. Retry from original code (not from the previous failed fix — prevents compounding errors).
2. Re-run ALL gates after each fix (prevents cascading regressions).
3. Max 3 attempts. After 3 failures → escalate to human with failure log.
4. Gate 3 (Visual Quality) is never auto-fixed — human always decides.

PM Hub Sync (Mandatory — follow /pm-hub-sync)

8. Update STATUS.md — check off UCs, update status, add key files.
9. Update plans/specs/README.md — status icon and documents column.
10. brv curate with what was built.

Auto-End (EVERY conversation)

// turbo

brv curate "{what was built and why}" -f {changed files}

🔄 Conversation Handoff Prompt (MANDATORY)

Rule: When suggesting to switch conversations, ALWAYS generate a ready-to-copy prompt for the user. Never just say "open a new conversation" without providing the prompt.

Format:

## 📋 Next Conversation Prompt (copy & paste)

```
Tiếp tục từ conversation trước: [1-line summary of what was done]

### Context
- Branch: `{branch-name}`
- Last commit: `{commit-hash}` — {commit message}
- STATUS: `plans/specs/{feature-id}/STATUS.md`

### What was completed
- [bullet list of completed items]

### Next steps
- [ ] [specific task 1]
- [ ] [specific task 2]

### Key files
- `{file1}` — {why relevant}
- `{file2}` — {why relevant}
```

Rules:

1. Include the exact branch and commit hash so context is verifiable
2. List specific next steps — not vague ("continue development")
3. Include key files the next conversation will need to touch
4. If there's a STATUS.md, reference it — the next conversation can brv query from there
5. Format as a fenced code block so user can copy with one click

Quick Reference