ui-syncup 0.3.13 → 0.4.0-beta.1

package/.agents/skills/brainstorming/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: brainstorming
+description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
+---
+
+# Brainstorming Ideas Into Designs
+
+## Overview
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
+
+## The Process
+
+**Understanding the idea:**
+- Check out the current project state first (files, docs, recent commits)
+- Ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Exploring approaches:**
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**Presenting the design:**
+- Once you believe you understand what you're building, present the design
+- Break it into sections of 200-300 words
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+## After the Design
+
+**Documentation:**
+- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
+- Use elements-of-style:writing-clearly-and-concisely skill if available
+- Commit the design document to git
+
+**Implementation (if continuing):**
+- Ask: "Ready to set up for implementation?"
+- Use superpowers:using-git-worktrees to create isolated workspace
+- Use superpowers:writing-plans to create detailed implementation plan
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design in sections, validate each
+- **Be flexible** - Go back and clarify when something doesn't make sense

package/.agents/skills/contract-driven-ui/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: contract-driven-ui
+description: Use when building any frontend page, component, or user flow before the real API is ready — when you need to scaffold UI from API contract shapes, generate typed fixture data, or wire up a mock service layer using docs/API_CONTRACTS_V1.md as source of truth.
+---
+
+# Contract-Driven UI Development
+
+## Overview
+
+Build real frontend UI from API contract shapes using typed fixture data — no backend required. The UI and backend develop in parallel; swap `USE_MOCK=false` when the real API ships.
+
+**Core principle:** The API contract is the source of truth. Fixtures must be strictly typed against contract shapes. Never invent fields.
+
+---
+
+## When to Use
+
+- Building any page/flow before the real API exists
+- Scaffolding a new feature from `docs/API_CONTRACTS_V1.md`
+- Designing all UI states (loading, empty, error, edge) for a page
+- Connecting frontend to a newly reviewed feature spec
+
+**Do NOT use** for: pages that already have a working API endpoint (use the real service instead).
+
+---
+
+## Step-by-Step Process
+
+### Step 1 — Read the Contract
+
+Always start here. Open `docs/API_CONTRACTS_V1.md` and locate:
+
+1. The endpoint(s) for the feature you're building
+2. The **request/response shape** (columns: `Request (shape)` and `Response (shape)`)
+3. The **error codes** the endpoint can return
+4. The **shared conventions** (Section 2) — especially the success/error envelopes and pagination contract
+
+**Key sections by feature:**
+
+| Feature | Section in API_CONTRACTS_V1.md |
+|---|---|
+| Auth / Session / Roles | §5.1 |
+| Ideas (submit, feed, detail) | §5.2 |
+| Campaigns | §5.3 |
+| Reactions / Boosts / Comments | §5.4 |
+| Governance Inbox / Scorecards | §5.5 |
+| Admin Config / Themes / Teams | §5.6 |
+| Notifications | §5.7 |
+| My Hub / Profile | §5.8 |
+| Analytics | §5.9 |
+| Gamification / XP | §5.10 |
+
+Also cross-reference `docs/developments/MVP_V1.md` for flow details and acceptance criteria.
+
+---
+
+### Step 2 — Define TypeScript Types
+
+Create or update `src/types/<module>.types.ts` using the contract shapes. Match field names exactly.
+
+```ts
+// src/types/idea.types.ts
+// Source: API_CONTRACTS_V1.md §5.2
+
+export type IdeaIntent = 'Problem' | 'Solution'
+export type IdeaStatus =
+  | 'Draft' | 'Submitted' | 'Open' | 'Shortlisted'
+  | 'Planned' | 'In Progress' | 'Launched' | 'Deferred' | 'Closed' | 'Resolved'
+
+export interface IdeaCard {
+  id: string
+  intent: IdeaIntent
+  title: string
+  status: IdeaStatus
+  themeId: string
+  themeName: string
+  authorDisplayName: string       // "Anonymous" when semi-anonymous
+  campaignId?: string
+  createdAt: string               // UTC ISO-8601
+  engagementSummary: {
+    viewCount: number
+    reactionCounts: Record<string, number>
+    boostCount: number
+    commentCount: number
+    signalScore: number
+  }
+  isCeoPick: boolean
+  reportCardPhase: ReportCardPhase
+}
+
+export type ReportCardPhase =
+  | 'Needs Signal'
+  | 'Awaiting Review Start'
+  | 'Under Review'
+  | 'Decision Published'
+```
+
+---
+
+### Step 3 — Write Realistic Fixture Files
+
+Create fixtures in `src/mocks/fixtures/<module>.fixtures.ts`.
+
+**Rules:**
+- Use Thai names, realistic KPC data (departments, ideas, campaigns)
+- Cover edge values: very long titles, zero counts, max counts
+- Use `null` / `undefined` for optional fields to catch rendering bugs
+- Use UTC ISO-8601 for all timestamps
+
+```ts
+// src/mocks/fixtures/ideas.fixtures.ts
+import type { IdeaCard } from '@/types/idea.types'
+
+export const mockIdeaCards: IdeaCard[] = [
+  {
+    id: 'idea_001',
+    intent: 'Problem',
+    title: 'ช่องทางสั่งซื้อ Duty Free สำหรับลูกค้า Transit ยังไม่ชัดเจน',
+    status: 'Open',
+    themeId: 'theme_cust_exp',
+    themeName: 'Customer Experience',
+    authorDisplayName: 'Anonymous',        // semi-anonymous
+    createdAt: '2026-02-01T08:30:00Z',
+    engagementSummary: {
+      viewCount: 342,
+      reactionCounts: { Like: 28, Love: 14, Insightful: 9 },
+      boostCount: 7,
+      commentCount: 12,
+      signalScore: 75,                     // (28+14+9)×1 + 12×2 + 7×5 = 86 — verify formula
+    },
+    isCeoPick: false,
+    reportCardPhase: 'Under Review',
+  },
+  // ... more fixtures covering all statuses and phases
+]
+
+// Edge case fixtures
+export const mockEmptyFeed: IdeaCard[] = []
+export const mockSingleIdea: IdeaCard[] = [mockIdeaCards[0]]
+```
+
+---
+
+### Step 4 — Create the Mock Service Layer
+
+Abstract all data fetching so the mock/real switch is one environment variable.
+
+```ts
+// src/services/ideas.service.ts
+import { mockIdeaCards } from '@/mocks/fixtures/ideas.fixtures'
+import type { IdeaCard } from '@/types/idea.types'
+
+const USE_MOCK = process.env.NEXT_PUBLIC_USE_MOCK === 'true'
+
+export async function getIdeas(params?: {
+  surface?: 'feed' | 'explore' | 'roadmap'
+  status?: string[]
+  page?: number
+  pageSize?: number
+}): Promise<{ items: IdeaCard[]; meta: PaginationMeta }> {
+  if (USE_MOCK) {
+    return {
+      items: mockIdeaCards,
+      meta: { page: 1, pageSize: 20, total: mockIdeaCards.length, hasNext: false },
+    }
+  }
+  const res = await fetch(`/api/v1/ideas?${new URLSearchParams(params as any)}`)
+  if (!res.ok) throw new Error(await res.text())
+  return res.json().then(r => r.data)
+}
+```
+
+---
+
+### Step 5 — Build All UI States
+
+For every page or component, implement **all states** before marking it done:
+
+| State | What to build |
+|---|---|
+| **Loading** | Skeleton / shimmer placeholders (match real layout) |
+| **Empty** | Zero-item state with helpful message, no blank white box |
+| **Error** | Error boundary or inline error with retry action |
+| **Partial data** | Optional fields missing (avatar, campaignId, etc.) |
+| **Full / Edge** | 50+ items, very long Thai text, max attachment count |
+| **Forbidden (403)** | Role-gated pages show correct "no access" state |
+
+---
+
+### Step 6 — Verify Against Contract Rules
+
+Before calling a page done, check these mandatory contract rules from `API_CONTRACTS_V1.md §2`:
+
+- [ ] **Success envelope**: unwrap `data` from `{ data: {}, meta: {} }`
+- [ ] **Error envelope**: handle `error.code`, show `error.message` (localized), use `error.details[].field` for form errors
+- [ ] **Pagination**: respect `hasNext` for infinite scroll / load more
+- [ ] **Timestamps**: display in user timezone (default `Asia/Bangkok` / `th-TH` locale per §2.10)
+- [ ] **Semi-anonymous**: show `"Anonymous"` wherever `authorDisplayName` is `"Anonymous"` — never reveal real name
+- [ ] **RBAC-gated UI**: hide/disable actions based on user role (see `docs/feature-definitions/AUTH_MODULE.md`)
+- [ ] **Attachment states**: only render `clean`-state attachments; show placeholder for `pending_scan`/`quarantined`
+
+---
+
+## File Structure
+
+```
+src/
+├── types/
+│   ├── idea.types.ts
+│   ├── governance.types.ts
+│   ├── engagement.types.ts
+│   └── shared.types.ts          ← PaginationMeta, ApiError, etc.
+├── mocks/
+│   └── fixtures/
+│       ├── ideas.fixtures.ts
+│       ├── users.fixtures.ts
+│       ├── governance.fixtures.ts
+│       └── notifications.fixtures.ts
+└── services/
+    ├── ideas.service.ts
+    ├── governance.service.ts
+    └── notifications.service.ts
+```
+
+---
+
+## Shared Types to Always Define
+
+These come from `API_CONTRACTS_V1.md §2` and are used everywhere:
+
+```ts
+// src/types/shared.types.ts
+
+export interface ApiMeta {
+  requestId: string
+  timestamp: string
+}
+
+export interface PaginationMeta extends ApiMeta {
+  page: number
+  pageSize: number
+  total: number
+  hasNext: boolean
+  sort?: string
+  order?: 'asc' | 'desc'
+  appliedFilters?: Record<string, unknown>
+  appliedSearch?: string | null
+}
+
+export interface ApiError {
+  code: string
+  message: string
+  details?: { field?: string; reason: string }[]
+  requestId: string
+}
+```
+
+---
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---|---|
+| Inventing fixture fields not in contract | Only use fields from the API contract shape tables |
+| `authorDisplayName` showing real name | Always check visibility: show `"Anonymous"` per §F3 rules |
+| Hardcoding `page=1` without pagination meta | Always wire up `PaginationMeta` even in mock |
+| Missing error states | Build 400/403/404/409/429 UI states for every mutation |
+| Timestamps in local format | Format all dates with user locale; default `th-TH`, `Asia/Bangkok` |
+| Skipping loading skeleton | Every async component needs a skeleton that matches its real layout |
+| Using boolean for attachment visibility | Check `attachment.scanStatus === 'clean'` per §2.6 |

package/.agents/skills/dispatching-parallel-agents/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: dispatching-parallel-agents
+description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
+---
+
+# Dispatching Parallel Agents
+
+## Overview
+
+When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
+
+**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Multiple failures?" [shape=diamond];
+    "Are they independent?" [shape=diamond];
+    "Single agent investigates all" [shape=box];
+    "One agent per problem domain" [shape=box];
+    "Can they work in parallel?" [shape=diamond];
+    "Sequential agents" [shape=box];
+    "Parallel dispatch" [shape=box];
+
+    "Multiple failures?" -> "Are they independent?" [label="yes"];
+    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
+    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
+    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
+    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
+}
+```
+
+**Use when:**
+- 3+ test files failing with different root causes
+- Multiple subsystems broken independently
+- Each problem can be understood without context from others
+- No shared state between investigations
+
+**Don't use when:**
+- Failures are related (fix one might fix others)
+- Need to understand full system state
+- Agents would interfere with each other
+
+## The Pattern
+
+### 1. Identify Independent Domains
+
+Group failures by what's broken:
+- File A tests: Tool approval flow
+- File B tests: Batch completion behavior
+- File C tests: Abort functionality
+
+Each domain is independent - fixing tool approval doesn't affect abort tests.
+
+### 2. Create Focused Agent Tasks
+
+Each agent gets:
+- **Specific scope:** One test file or subsystem
+- **Clear goal:** Make these tests pass
+- **Constraints:** Don't change other code
+- **Expected output:** Summary of what you found and fixed
+
+### 3. Dispatch in Parallel
+
+```typescript
+// In Claude Code / AI environment
+Task("Fix agent-tool-abort.test.ts failures")
+Task("Fix batch-completion-behavior.test.ts failures")
+Task("Fix tool-approval-race-conditions.test.ts failures")
+// All three run concurrently
+```
+
+### 4. Review and Integrate
+
+When agents return:
+- Read each summary
+- Verify fixes don't conflict
+- Run full test suite
+- Integrate all changes
+
+## Agent Prompt Structure
+
+Good agent prompts are:
+1. **Focused** - One clear problem domain
+2. **Self-contained** - All context needed to understand the problem
+3. **Specific about output** - What should the agent return?
+
+```markdown
+Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:
+
+1. "should abort tool with partial output capture" - expects 'interrupted at' in message
+2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
+3. "should properly track pendingToolCount" - expects 3 results but gets 0
+
+These are timing/race condition issues. Your task:
+
+1. Read the test file and understand what each test verifies
+2. Identify root cause - timing issues or actual bugs?
+3. Fix by:
+   - Replacing arbitrary timeouts with event-based waiting
+   - Fixing bugs in abort implementation if found
+   - Adjusting test expectations if testing changed behavior
+
+Do NOT just increase timeouts - find the real issue.
+
+Return: Summary of what you found and what you fixed.
+```
+
+## Common Mistakes
+
+**❌ Too broad:** "Fix all the tests" - agent gets lost
+**✅ Specific:** "Fix agent-tool-abort.test.ts" - focused scope
+
+**❌ No context:** "Fix the race condition" - agent doesn't know where
+**✅ Context:** Paste the error messages and test names
+
+**❌ No constraints:** Agent might refactor everything
+**✅ Constraints:** "Do NOT change production code" or "Fix tests only"
+
+**❌ Vague output:** "Fix it" - you don't know what changed
+**✅ Specific:** "Return summary of root cause and changes"
+
+## When NOT to Use
+
+**Related failures:** Fixing one might fix others - investigate together first
+**Need full context:** Understanding requires seeing entire system
+**Exploratory debugging:** You don't know what's broken yet
+**Shared state:** Agents would interfere (editing same files, using same resources)
+
+## Real Example from Session
+
+**Scenario:** 6 test failures across 3 files after major refactoring
+
+**Failures:**
+- agent-tool-abort.test.ts: 3 failures (timing issues)
+- batch-completion-behavior.test.ts: 2 failures (tools not executing)
+- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
+
+**Decision:** Independent domains - abort logic separate from batch completion separate from race conditions
+
+**Dispatch:**
+```
+Agent 1 → Fix agent-tool-abort.test.ts
+Agent 2 → Fix batch-completion-behavior.test.ts
+Agent 3 → Fix tool-approval-race-conditions.test.ts
+```
+
+**Results:**
+- Agent 1: Replaced timeouts with event-based waiting
+- Agent 2: Fixed event structure bug (threadId in wrong place)
+- Agent 3: Added wait for async tool execution to complete
+
+**Integration:** All fixes independent, no conflicts, full suite green
+
+**Time saved:** 3 problems solved in parallel vs sequentially
+
+## Key Benefits
+
+1. **Parallelization** - Multiple investigations happen simultaneously
+2. **Focus** - Each agent has narrow scope, less context to track
+3. **Independence** - Agents don't interfere with each other
+4. **Speed** - 3 problems solved in time of 1
+
+## Verification
+
+After agents return:
+1. **Review each summary** - Understand what changed
+2. **Check for conflicts** - Did agents edit same code?
+3. **Run full suite** - Verify all fixes work together
+4. **Spot check** - Agents can make systematic errors
+
+## Real-World Impact
+
+From debugging session (2025-10-03):
+- 6 failures across 3 files
+- 3 agents dispatched in parallel
+- All investigations completed concurrently
+- All fixes integrated successfully
+- Zero conflicts between agent changes

package/.agents/skills/executing-plans/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: executing-plans
+description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
+---
+
+# Executing Plans
+
+## Overview
+
+Load plan, review critically, execute tasks in batches, report for review between batches.
+
+**Core principle:** Batch execution with checkpoints for architect review.
+
+**Announce at start:** "I'm using the executing-plans skill to implement this plan."
+
+## The Process
+
+### Step 1: Load and Review Plan
+1. Read plan file
+2. Review critically - identify any questions or concerns about the plan
+3. If concerns: Raise them with your human partner before starting
+4. If no concerns: Create TodoWrite and proceed
+
+### Step 2: Execute Batch
+**Default: First 3 tasks**
+
+For each task:
+1. Mark as in_progress
+2. Follow each step exactly (plan has bite-sized steps)
+3. Run verifications as specified
+4. Mark as completed
+
+### Step 3: Report
+When batch complete:
+- Show what was implemented
+- Show verification output
+- Say: "Ready for feedback."
+
+### Step 4: Continue
+Based on feedback:
+- Apply changes if needed
+- Execute next batch
+- Repeat until complete
+
+### Step 5: Complete Development
+
+After all tasks complete and verified:
+- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
+- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
+- Follow that skill to verify tests, present options, execute choice
+
+## When to Stop and Ask for Help
+
+**STOP executing immediately when:**
+- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
+- Plan has critical gaps preventing starting
+- You don't understand an instruction
+- Verification fails repeatedly
+
+**Ask for clarification rather than guessing.**
+
+## When to Revisit Earlier Steps
+
+**Return to Review (Step 1) when:**
+- Partner updates the plan based on your feedback
+- Fundamental approach needs rethinking
+
+**Don't force through blockers** - stop and ask.
+
+## Remember
+- Review plan critically first
+- Follow plan steps exactly
+- Don't skip verifications
+- Reference skills when plan says to
+- Between batches: just report and wait
+- Stop when blocked, don't guess

package/.agents/skills/executing-specs/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: executing-specs
+description: Executes a specific task from a specification suite, adhering to requirements, design, and project guidelines. Use when the user asks to execute a task from .ai/specs.
+---
+
+# Execute Specification Task
+
+## When to use this skill
+- User asks to "Execute Task [Task Name]" from a tasks.md file.
+- User provides a path to a task file and asks to implement it.
+- User references `.ai/specs` tasks.
+
+## Workflow
+1.  **Context Assembly (Critical)**
+    - **Derive Spec Folder**: The spec folder is the **parent directory** of the provided `tasks.md` file.
+        - Example: If user says "Execute Task X in `.ai/specs/example-feature/tasks.md`", the spec folder is `.ai/specs/example-feature/`.
+    - **Read Task**: `view_file` the provided `tasks.md` to find the specific task title and its context/subtasks.
+    - **Read Sibling Specs**: Read all other relevant files in the **same spec folder**:
+        - `requirements.md` (the "what")
+        - `design.md` (the "how")
+        - Any other `.md` files in that folder (e.g., `review.md`).
+    - **Read Governance**: Read `.ai/steering/tech.md`, `.ai/steering/structure.md`, and `.ai/steering/product.md`.
+    - **Read Persona**: Read `AGENTS.md` to adopt the "Craftsman" persona and constraints.
+
+2.  **Persona Adoption**
+    - Adopt the persona defined in `AGENTS.md` ("You're not just an AI assistant. You're a craftsman...").
+    - Adhere strictly to the "Core Principles" and "Layer Contracts" defined in `AGENTS.md`.
+
+3.  **Planning (Plan)**
+    - Create or update `implementation_plan.md` in the artifact directory.
+    - Map the task requirements to specific code changes.
+    - **Clarify**: If requirements are ambiguous, ASK the user immediately. Do not guess.
+
+4.  **Implementation (Execute)**
+    - **Task Boundary**: Use `task_boundary` to track progress.
+    - **Code**: Write code that matches the project structure (`feature-first`, `strict layering`).
+    - **Styles**: Ensure UI matches the "Premium" and "Dynamic" aesthetic guidelines.
+
+5.  **Verification**
+    - Verify changes against the specific requirements in `requirements.md`.
+    - Run applicable tests (`bun run test`).
+    - Mark the task as `[x]` in the original `tasks.md` file (using `multi_replace_file_content`).
+
+## Instructions
+- **Strict Compliance**: You must follow the **Directory Structure** and **Layer Contracts** from `AGENTS.md`.
+    - e.g., No importing `features/*` from `components/shared`.
+- **Constraint check**: Before writing code, check: "Does this violate `AGENTS.md` or `.ai/steering`?"
+- **Atomic Execution**: Focus ONLY on the requested task. Do not implement future tasks or other items in the checklist unless explicitly asked.
+- **Reporting**: When finished, summarize what was built and referencing the specific requirements met.
+
+## Resources
+- [Project Scaffolding & Persona](../../../../AGENTS.md)
+- [Steering Guidelines](../../../../.ai/steering/)