codingbuddy-rules 4.4.0 → 5.0.0

package/.ai-rules/skills/widget-slot-architecture/examples/parallel-route-setup.tsx

@@ -0,0 +1,206 @@
+/**
+ * Parallel Route Setup Example
+ *
+ * Demonstrates how to set up a complete Next.js App Router page
+ * with multiple Parallel Route slots following the Widget-Slot Architecture.
+ *
+ * File structure this example represents:
+ *
+ * app/dashboard/
+ * ├── layout.tsx              ← Root layout defining slot positions
+ * ├── page.tsx                ← Main content (children)
+ * ├── @sidebar/
+ * │   ├── page.tsx            ← Sidebar slot (imports SidebarWidget)
+ * │   ├── loading.tsx         ← Sidebar loading state
+ * │   ├── error.tsx           ← Sidebar error boundary
+ * │   └── default.tsx         ← Sidebar fallback
+ * └── @activity/
+ *     ├── page.tsx            ← Activity slot (imports ActivityWidget)
+ *     ├── loading.tsx         ← Activity loading state
+ *     ├── error.tsx           ← Activity error boundary
+ *     └── default.tsx         ← Activity fallback
+ */
+
+// ═══════════════════════════════════════════════════════════
+// 1. Dashboard Layout — defines slot positions (static shell)
+// File: app/dashboard/layout.tsx
+// ═══════════════════════════════════════════════════════════
+
+import { type ReactNode } from 'react';
+
+interface DashboardLayoutProps {
+  children: ReactNode;    // Main content (app/dashboard/page.tsx)
+  sidebar: ReactNode;     // Parallel route: @sidebar
+  activity: ReactNode;    // Parallel route: @activity
+}
+
+export default function DashboardLayout({
+  children,
+  sidebar,
+  activity,
+}: DashboardLayoutProps) {
+  return (
+    <div className="dashboard-layout">
+      {/* Static shell — no business logic, only structure */}
+      <aside className="dashboard-layout__sidebar">
+        {sidebar}
+      </aside>
+      <main className="dashboard-layout__content">
+        {children}
+      </main>
+      <section className="dashboard-layout__activity">
+        {activity}
+      </section>
+    </div>
+  );
+}
+
+// ═══════════════════════════════════════════════════════════
+// 2. Slot Page — connects one Widget to one Slot
+// File: app/dashboard/@sidebar/page.tsx
+// ═══════════════════════════════════════════════════════════
+
+// import NavigationWidget from '@/Widgets/Navigation';
+//
+// export default function SidebarSlotPage() {
+//   return <NavigationWidget section="dashboard" />;
+// }
+
+// ═══════════════════════════════════════════════════════════
+// 3. Slot Loading — independent loading state per slot
+// File: app/dashboard/@sidebar/loading.tsx
+// ═══════════════════════════════════════════════════════════
+
+export function SidebarLoading() {
+  return (
+    <div className="slot-loading" aria-label="Loading sidebar">
+      <div className="slot-loading__skeleton" style={{ height: '2rem', width: '60%' }} />
+      <div className="slot-loading__skeleton" style={{ height: '1rem', width: '80%' }} />
+      <div className="slot-loading__skeleton" style={{ height: '1rem', width: '70%' }} />
+      <div className="slot-loading__skeleton" style={{ height: '1rem', width: '75%' }} />
+    </div>
+  );
+}
+
+// ═══════════════════════════════════════════════════════════
+// 4. Slot Error — fault isolation per slot
+// File: app/dashboard/@sidebar/error.tsx
+// ═══════════════════════════════════════════════════════════
+
+// 'use client';  ← error.tsx must be a Client Component
+//
+// interface SlotErrorProps {
+//   error: Error & { digest?: string };
+//   reset: () => void;
+// }
+//
+// export default function SidebarError({ error, reset }: SlotErrorProps) {
+//   return (
+//     <div className="slot-error" role="alert">
+//       <p className="slot-error__message">
+//         This section encountered an issue.
+//       </p>
+//       <button
+//         className="slot-error__retry"
+//         onClick={reset}
+//         type="button"
+//       >
+//         Try again
+//       </button>
+//     </div>
+//   );
+// }
+
+// ═══════════════════════════════════════════════════════════
+// 5. Slot Default — fallback when no matching route
+// File: app/dashboard/@sidebar/default.tsx
+// ═══════════════════════════════════════════════════════════
+
+export function SidebarDefault() {
+  return (
+    <div className="slot-default">
+      <p>Select a section to view navigation.</p>
+    </div>
+  );
+}
+
+// ═══════════════════════════════════════════════════════════
+// 6. CSS — Dashboard layout styles
+// File: app/dashboard/dashboard.module.css
+// ═══════════════════════════════════════════════════════════
+
+/*
+.dashboard-layout {
+  display: grid;
+  grid-template-columns: 280px 1fr 320px;
+  grid-template-rows: 1fr;
+  min-height: 100dvh;
+  gap: 0;
+}
+
+.dashboard-layout__sidebar {
+  border-right: 1px solid var(--color-border);
+  overflow-y: auto;
+}
+
+.dashboard-layout__content {
+  padding: clamp(1rem, 3vw, 2rem);
+  overflow-y: auto;
+}
+
+.dashboard-layout__activity {
+  border-left: 1px solid var(--color-border);
+  overflow-y: auto;
+}
+
+/* Responsive: stack on mobile */
+@media (max-width: 768px) {
+  .dashboard-layout {
+    grid-template-columns: 1fr;
+    grid-template-rows: auto 1fr auto;
+  }
+  .dashboard-layout__sidebar {
+    border-right: none;
+    border-bottom: 1px solid var(--color-border);
+  }
+  .dashboard-layout__activity {
+    border-left: none;
+    border-top: 1px solid var(--color-border);
+  }
+}
+
+/* Slot loading skeleton */
+.slot-loading {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  padding: 1.5rem;
+}
+
+.slot-loading__skeleton {
+  background: linear-gradient(90deg, var(--color-surface-raised) 25%, var(--color-border) 50%, var(--color-surface-raised) 75%);
+  background-size: 200% 100%;
+  animation: shimmer 1.5s ease-in-out infinite;
+  border-radius: 0.25rem;
+}
+
+@keyframes shimmer {
+  0% { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+
+/* Slot error */
+.slot-error {
+  padding: 1.5rem;
+  text-align: center;
+}
+
+.slot-error__retry {
+  margin-top: 0.75rem;
+  padding: 0.5rem 1rem;
+  border: 1px solid var(--color-border);
+  border-radius: 0.375rem;
+  background: var(--color-surface);
+  cursor: pointer;
+}
+*/

package/.ai-rules/skills/widget-slot-architecture/examples/widget-component.tsx

@@ -0,0 +1,250 @@
+/**
+ * Widget Component Example
+ *
+ * Demonstrates a complete Widget following the Widget-Slot Architecture:
+ * - Server Component entry point (data fetching)
+ * - Client Component UI (interactions)
+ * - Colocated Server Actions (mutations)
+ * - Barrel file exports
+ *
+ * File structure:
+ *
+ * Widgets/TaskBoard/
+ * ├── index.tsx           ← Entry point (this file concept - Server Component)
+ * ├── types.ts            ← Widget-specific types
+ * ├── ui/
+ * │   ├── index.ts        ← Barrel file
+ * │   ├── TaskBoardUI.tsx  ← Main UI (Client Component)
+ * │   └── TaskCard.tsx     ← Sub-component (Client Component)
+ * ├── hooks/
+ * │   └── useTaskDrag.ts  ← Widget-specific hook
+ * └── actions/
+ *     ├── getTasks.ts     ← Data fetching (cached)
+ *     └── updateTask.ts   ← Data mutation (revalidates)
+ */
+
+// ═══════════════════════════════════════════════════════════
+// types.ts — Widget-specific types
+// ═══════════════════════════════════════════════════════════
+
+export interface Task {
+  id: string;
+  title: string;
+  status: 'todo' | 'in_progress' | 'done';
+  assignee: string | null;
+  priority: 'low' | 'medium' | 'high';
+  createdAt: string;
+}
+
+export interface TaskBoardProps {
+  /** Project identifier to fetch tasks for */
+  projectId: string;
+  /** Optional filter for task status */
+  statusFilter?: Task['status'][];
+}
+
+// ═══════════════════════════════════════════════════════════
+// actions/getTasks.ts — Cached data fetching
+// ═══════════════════════════════════════════════════════════
+
+// 'use server';
+// import { cache } from 'react';
+
+/**
+ * Fetch tasks for a project. Results are cached with a tag
+ * so other widgets can trigger re-fetch via revalidateTag.
+ */
+// export const getTasks = cache(async (projectId: string): Promise<Task[]> => {
+//   const res = await fetch(`${process.env.API_URL}/projects/${projectId}/tasks`, {
+//     next: { tags: [`tasks-${projectId}`] },
+//   });
+//
+//   if (!res.ok) {
+//     throw new Error(`Failed to fetch tasks: ${res.status}`);
+//   }
+//
+//   return res.json();
+// });
+
+// ═══════════════════════════════════════════════════════════
+// actions/updateTask.ts — Data mutation with cache invalidation
+// ═══════════════════════════════════════════════════════════
+
+// 'use server';
+// import { revalidateTag } from 'next/cache';
+
+/**
+ * Update a task's status. After mutation, invalidates the cache tag
+ * so all widgets consuming this project's tasks will re-fetch.
+ */
+// export async function updateTaskStatus(
+//   projectId: string,
+//   taskId: string,
+//   newStatus: Task['status'],
+// ): Promise<{ success: boolean }> {
+//   const res = await fetch(
+//     `${process.env.API_URL}/projects/${projectId}/tasks/${taskId}`,
+//     {
+//       method: 'PATCH',
+//       headers: { 'Content-Type': 'application/json' },
+//       body: JSON.stringify({ status: newStatus }),
+//     },
+//   );
+//
+//   if (!res.ok) {
+//     throw new Error(`Failed to update task: ${res.status}`);
+//   }
+//
+//   // Invalidate cache so all widgets showing these tasks re-fetch
+//   revalidateTag(`tasks-${projectId}`);
+//
+//   return { success: true };
+// }
+
+// ═══════════════════════════════════════════════════════════
+// index.tsx — Widget Entry Point (Server Component)
+// ═══════════════════════════════════════════════════════════
+
+/**
+ * TaskBoard Widget — Server Component entry point.
+ *
+ * Principles:
+ * 1. Receives only minimal props (projectId) — fetches own data
+ * 2. Starts as Server Component — delegates interactivity to Client UI
+ * 3. Portable — works in any slot that provides a projectId
+ */
+
+// import { getTasks } from './actions/getTasks';
+// import { TaskBoardUI } from './ui';
+//
+// export default async function TaskBoardWidget({
+//   projectId,
+//   statusFilter,
+// }: TaskBoardProps) {
+//   const allTasks = await getTasks(projectId);
+//
+//   const tasks = statusFilter
+//     ? allTasks.filter((t) => statusFilter.includes(t.status))
+//     : allTasks;
+//
+//   if (tasks.length === 0) {
+//     return (
+//       <div className="task-board--empty">
+//         <p>No tasks found. Create your first task to get started.</p>
+//       </div>
+//     );
+//   }
+//
+//   return <TaskBoardUI tasks={tasks} projectId={projectId} />;
+// }
+
+// ═══════════════════════════════════════════════════════════
+// ui/TaskBoardUI.tsx — Main UI (Client Component)
+// ═══════════════════════════════════════════════════════════
+
+// 'use client';
+//
+// import { type Task } from '../types';
+// import { TaskCard } from './TaskCard';
+// import { updateTaskStatus } from '../actions/updateTask';
+//
+// interface TaskBoardUIProps {
+//   tasks: Task[];
+//   projectId: string;
+// }
+//
+// const COLUMNS: Array<{ status: Task['status']; label: string }> = [
+//   { status: 'todo', label: 'To Do' },
+//   { status: 'in_progress', label: 'In Progress' },
+//   { status: 'done', label: 'Done' },
+// ];
+//
+// export function TaskBoardUI({ tasks, projectId }: TaskBoardUIProps) {
+//   const handleStatusChange = async (taskId: string, newStatus: Task['status']) => {
+//     await updateTaskStatus(projectId, taskId, newStatus);
+//   };
+//
+//   return (
+//     <div className="task-board">
+//       {COLUMNS.map(({ status, label }) => (
+//         <div key={status} className="task-board__column">
+//           <h3 className="task-board__column-header">
+//             {label}
+//             <span className="task-board__count">
+//               {tasks.filter((t) => t.status === status).length}
+//             </span>
+//           </h3>
+//           <div className="task-board__cards">
+//             {tasks
+//               .filter((t) => t.status === status)
+//               .map((task) => (
+//                 <TaskCard
+//                   key={task.id}
+//                   task={task}
+//                   onStatusChange={handleStatusChange}
+//                 />
+//               ))}
+//           </div>
+//         </div>
+//       ))}
+//     </div>
+//   );
+// }
+
+// ═══════════════════════════════════════════════════════════
+// ui/TaskCard.tsx — Sub-component (Client Component)
+// ═══════════════════════════════════════════════════════════
+
+// 'use client';
+//
+// import { type Task } from '../types';
+//
+// interface TaskCardProps {
+//   task: Task;
+//   onStatusChange: (taskId: string, newStatus: Task['status']) => Promise<void>;
+// }
+//
+// const PRIORITY_COLORS: Record<Task['priority'], string> = {
+//   low: 'var(--color-success)',
+//   medium: 'var(--color-warning)',
+//   high: 'var(--color-danger)',
+// };
+//
+// export function TaskCard({ task, onStatusChange }: TaskCardProps) {
+//   return (
+//     <article className="task-card" data-priority={task.priority}>
+//       <div
+//         className="task-card__priority-indicator"
+//         style={{ backgroundColor: PRIORITY_COLORS[task.priority] }}
+//         aria-label={`Priority: ${task.priority}`}
+//       />
+//       <h4 className="task-card__title">{task.title}</h4>
+//       {task.assignee && (
+//         <span className="task-card__assignee">{task.assignee}</span>
+//       )}
+//     </article>
+//   );
+// }
+
+// ═══════════════════════════════════════════════════════════
+// ui/index.ts — Barrel file
+// ═══════════════════════════════════════════════════════════
+
+// export { TaskBoardUI } from './TaskBoardUI';
+// export { TaskCard } from './TaskCard';
+
+// ═══════════════════════════════════════════════════════════
+// Slot connection example
+// File: app/dashboard/@tasks/page.tsx
+// ═══════════════════════════════════════════════════════════
+
+// import TaskBoardWidget from '@/Widgets/TaskBoard';
+//
+// export default function TasksSlotPage({
+//   searchParams,
+// }: {
+//   searchParams: { project?: string };
+// }) {
+//   const projectId = searchParams.project ?? 'default';
+//   return <TaskBoardWidget projectId={projectId} />;
+// }

package/.ai-rules/skills/writing-plans/SKILL.md

@@ -41,9 +41,75 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
 
 **Tech Stack:** [Key technologies/libraries]
 
+## Alternatives
+
+### [Decision: e.g. State Management Approach]
+
+| Criteria | Approach A: [Name] | Approach B: [Name] |
+|---|---|---|
+| Performance | ... | ... |
+| Complexity | ... | ... |
+| Maintainability | ... | ... |
+
+**Decision:** [Chosen approach] — [One-line rationale]
+
 ---
 ```
 
+## Alternatives Exploration
+
+Every non-trivial decision in the plan MUST include at least two approaches with trade-off analysis.
+
+**What counts as non-trivial:**
+- Architecture choices (e.g. where to put new code)
+- Data flow design (e.g. state management approach)
+- API design (e.g. endpoint structure, payload shape)
+- Testing strategy (e.g. unit vs integration)
+
+**What does NOT need alternatives:**
+- File naming that follows existing conventions
+- Import statements
+- Trivial implementation details
+
+**Format for each decision:**
+
+```markdown
+### [Decision: Short Description]
+
+| Criteria | Approach A: [Name] | Approach B: [Name] |
+|---|---|---|
+| Performance | ... | ... |
+| Complexity | ... | ... |
+| Maintainability | ... | ... |
+
+**Decision:** [Chosen approach] — [One-line rationale]
+```
+
+**Rules:**
+- Minimum 2 approaches per non-trivial decision
+- Always include performance, complexity, and maintainability rows
+- Add extra criteria rows when relevant (e.g. security, testability, migration cost)
+- State the chosen approach with a clear rationale
+- If only one viable approach exists, explain why alternatives were ruled out
+
+## API Verification
+
+When the plan references external APIs, SDKs, or protocols:
+
+1. **Document every API assumption** with its source URL
+2. **Create an "API Assumptions" table** in the plan:
+
+| Assumption | Verified? | Source |
+|-----------|:---------:|--------|
+| Hook stdin has `tool_name` | ✅ | [Hooks Reference](url) |
+| Hook stdin has `session_cost` | ❌ UNVERIFIED | — |
+
+1. **All assumptions must be verified before ACT phase**
+2. **WebFetch/WebSearch the official docs** — never rely on memory or guesses
+
+### Why This Matters
+Unverified API assumptions propagate into implementation, causing features to be unimplementable as designed. Verification at PLAN time costs minutes; rework at ACT time costs hours.
+
 ## Task Structure
 
 ```markdown
@@ -94,6 +160,18 @@ git commit -m "feat: add specific feature"
 - Reference relevant skills with @ syntax
 - DRY, YAGNI, TDD, frequent commits
 
+## Self-Review Gate
+
+**Before submitting the plan, verify ALL items pass:**
+
+- [ ] All file paths verified (existing files confirmed, new files marked as `Create:`)
+- [ ] Steps are bite-sized (2-5 minutes each, one action per step)
+- [ ] Risks identified with mitigation (what could go wrong and how to handle it)
+- [ ] TDD applied where appropriate (test-first for core logic, test-after for UI)
+- [ ] No over-engineering (YAGNI check — remove anything not directly needed)
+
+**If any item fails:** Fix the plan before proceeding. Do not hand off an incomplete plan.
+
 ## Execution Handoff
 
 After saving the plan, offer execution choice: