beads-orchestration 2.0.0

package/templates/skills/react-best-practices/SKILL.md

@@ -0,0 +1,487 @@
+---
+name: react-best-practices
+description: React and Next.js performance optimization patterns. Use BEFORE implementing any React code to ensure best practices are followed.
+---
+
+# React Best Practices
+
+**Version 1.0.0**
+Source: Vercel Engineering (vercel-labs/agent-skills)
+
+> **Note:**
+> This document is for agents and LLMs to follow when maintaining,
+> generating, or refactoring React and Next.js codebases. Contains 40+ rules across 8 categories, prioritized by impact.
+
+---
+
+## How to Use This Skill
+
+**Before implementing ANY React/Next.js code:**
+
+1. Review the relevant sections based on what you're building
+2. Apply the patterns as you write code
+3. Use the "Incorrect" vs "Correct" examples as templates
+
+**Priority order:** Eliminating Waterfalls > Bundle Size > Server-Side > Client-Side > Re-renders > Rendering > JS Perf > Advanced
+
+---
+
+## Quick Reference: Critical Rules
+
+### Top 5 Rules (Always Apply)
+
+1. **Promise.all() for independent operations** - Never sequential awaits for independent data
+2. **Avoid barrel file imports** - Import directly from source files
+3. **Dynamic imports for heavy components** - Lazy-load Monaco, charts, etc.
+4. **Parallel data fetching with component composition** - Structure RSC for parallelism
+5. **Minimize serialization at RSC boundaries** - Only pass needed fields to client
+
+---
+
+## 1. Eliminating Waterfalls
+
+**Impact: CRITICAL** - Waterfalls are the #1 performance killer.
+
+### 1.1 Defer Await Until Needed
+
+Move `await` into branches where actually used.
+
+```typescript
+// BAD: blocks both branches
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  const userData = await fetchUserData(userId)
+  if (skipProcessing) return { skipped: true }
+  return processUserData(userData)
+}
+
+// GOOD: only blocks when needed
+async function handleRequest(userId: string, skipProcessing: boolean) {
+  if (skipProcessing) return { skipped: true }
+  const userData = await fetchUserData(userId)
+  return processUserData(userData)
+}
+```
+
+### 1.2 Promise.all() for Independent Operations
+
+```typescript
+// BAD: 3 round trips
+const user = await fetchUser()
+const posts = await fetchPosts()
+const comments = await fetchComments()
+
+// GOOD: 1 round trip
+const [user, posts, comments] = await Promise.all([
+  fetchUser(),
+  fetchPosts(),
+  fetchComments()
+])
+```
+
+### 1.3 Strategic Suspense Boundaries
+
+```tsx
+// BAD: wrapper blocked by data
+async function Page() {
+  const data = await fetchData()
+  return (
+    <div>
+      <Sidebar />
+      <DataDisplay data={data} />
+      <Footer />
+    </div>
+  )
+}
+
+// GOOD: wrapper shows immediately
+function Page() {
+  return (
+    <div>
+      <Sidebar />
+      <Suspense fallback={<Skeleton />}>
+        <DataDisplay />
+      </Suspense>
+      <Footer />
+    </div>
+  )
+}
+```
+
+---
+
+## 2. Bundle Size Optimization
+
+**Impact: CRITICAL** - Reduces TTI and LCP.
+
+### 2.1 Avoid Barrel File Imports
+
+```tsx
+// BAD: loads 1,583 modules
+import { Check, X, Menu } from 'lucide-react'
+
+// GOOD: loads only 3 modules
+import Check from 'lucide-react/dist/esm/icons/check'
+import X from 'lucide-react/dist/esm/icons/x'
+import Menu from 'lucide-react/dist/esm/icons/menu'
+
+// ALTERNATIVE: Next.js 13.5+ config
+// next.config.js
+module.exports = {
+  experimental: {
+    optimizePackageImports: ['lucide-react', '@mui/material']
+  }
+}
+```
+
+### 2.2 Dynamic Imports for Heavy Components
+
+```tsx
+// BAD: Monaco bundles with main chunk (~300KB)
+import { MonacoEditor } from './monaco-editor'
+
+// GOOD: Monaco loads on demand
+import dynamic from 'next/dynamic'
+const MonacoEditor = dynamic(
+  () => import('./monaco-editor').then(m => m.MonacoEditor),
+  { ssr: false }
+)
+```
+
+### 2.3 Defer Non-Critical Libraries
+
+```tsx
+// BAD: blocks initial bundle
+import { Analytics } from '@vercel/analytics/react'
+
+// GOOD: loads after hydration
+import dynamic from 'next/dynamic'
+const Analytics = dynamic(
+  () => import('@vercel/analytics/react').then(m => m.Analytics),
+  { ssr: false }
+)
+```
+
+### 2.4 Preload on User Intent
+
+```tsx
+function EditorButton({ onClick }: { onClick: () => void }) {
+  const preload = () => {
+    if (typeof window !== 'undefined') {
+      void import('./monaco-editor')
+    }
+  }
+  return (
+    <button onMouseEnter={preload} onFocus={preload} onClick={onClick}>
+      Open Editor
+    </button>
+  )
+}
+```
+
+---
+
+## 3. Server-Side Performance
+
+**Impact: HIGH**
+
+### 3.1 Minimize Serialization at RSC Boundaries
+
+```tsx
+// BAD: serializes all 50 fields
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+// GOOD: serializes only needed fields
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} avatar={user.avatar} />
+}
+```
+
+### 3.2 Parallel Data Fetching with Component Composition
+
+```tsx
+// BAD: Sidebar waits for Header's fetch
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+// GOOD: both fetch simultaneously
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+### 3.3 Per-Request Deduplication with React.cache()
+
+```typescript
+import { cache } from 'react'
+
+export const getCurrentUser = cache(async () => {
+  const session = await auth()
+  if (!session?.user?.id) return null
+  return await db.user.findUnique({ where: { id: session.user.id } })
+})
+```
+
+### 3.4 Use after() for Non-Blocking Operations
+
+```tsx
+import { after } from 'next/server'
+
+export async function POST(request: Request) {
+  await updateDatabase(request)
+
+  // Log after response is sent
+  after(async () => {
+    const userAgent = (await headers()).get('user-agent')
+    logUserAction({ userAgent })
+  })
+
+  return Response.json({ status: 'success' })
+}
+```
+
+---
+
+## 4. Client-Side Data Fetching
+
+**Impact: MEDIUM-HIGH**
+
+### 4.1 Use SWR for Automatic Deduplication
+
+```tsx
+// BAD: no deduplication
+function UserList() {
+  const [users, setUsers] = useState([])
+  useEffect(() => {
+    fetch('/api/users').then(r => r.json()).then(setUsers)
+  }, [])
+}
+
+// GOOD: multiple instances share one request
+import useSWR from 'swr'
+function UserList() {
+  const { data: users } = useSWR('/api/users', fetcher)
+}
+```
+
+---
+
+## 5. Re-render Optimization
+
+**Impact: MEDIUM**
+
+### 5.1 Use Functional setState Updates
+
+```tsx
+// BAD: requires state as dependency, risk of stale closure
+const addItems = useCallback((newItems: Item[]) => {
+  setItems([...items, ...newItems])
+}, [items])
+
+// GOOD: stable callback, no stale closures
+const addItems = useCallback((newItems: Item[]) => {
+  setItems(curr => [...curr, ...newItems])
+}, [])
+```
+
+### 5.2 Use Lazy State Initialization
+
+```tsx
+// BAD: runs on every render
+const [settings] = useState(JSON.parse(localStorage.getItem('settings') || '{}'))
+
+// GOOD: runs only once
+const [settings] = useState(() => {
+  const stored = localStorage.getItem('settings')
+  return stored ? JSON.parse(stored) : {}
+})
+```
+
+### 5.3 Use Transitions for Non-Urgent Updates
+
+```tsx
+import { startTransition } from 'react'
+
+function ScrollTracker() {
+  const [scrollY, setScrollY] = useState(0)
+  useEffect(() => {
+    const handler = () => {
+      startTransition(() => setScrollY(window.scrollY))
+    }
+    window.addEventListener('scroll', handler, { passive: true })
+    return () => window.removeEventListener('scroll', handler)
+  }, [])
+}
+```
+
+### 5.4 Narrow Effect Dependencies
+
+```tsx
+// BAD: re-runs on any user field change
+useEffect(() => {
+  console.log(user.id)
+}, [user])
+
+// GOOD: re-runs only when id changes
+useEffect(() => {
+  console.log(user.id)
+}, [user.id])
+```
+
+---
+
+## 6. Rendering Performance
+
+**Impact: MEDIUM**
+
+### 6.1 CSS content-visibility for Long Lists
+
+```css
+.message-item {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 80px;
+}
+```
+
+### 6.2 Hoist Static JSX Elements
+
+```tsx
+// BAD: recreates element every render
+function Container() {
+  return loading && <div className="animate-pulse h-20 bg-gray-200" />
+}
+
+// GOOD: reuses same element
+const loadingSkeleton = <div className="animate-pulse h-20 bg-gray-200" />
+function Container() {
+  return loading && loadingSkeleton
+}
+```
+
+### 6.3 Animate SVG Wrapper, Not SVG Element
+
+```tsx
+// BAD: no hardware acceleration
+<svg className="animate-spin">...</svg>
+
+// GOOD: hardware accelerated
+<div className="animate-spin">
+  <svg>...</svg>
+</div>
+```
+
+---
+
+## 7. JavaScript Performance
+
+**Impact: LOW-MEDIUM**
+
+### 7.1 Build Index Maps for Repeated Lookups
+
+```typescript
+// BAD: O(n) per lookup
+items.filter(item => allowedIds.includes(item.id))
+
+// GOOD: O(1) per lookup
+const allowedSet = new Set(allowedIds)
+items.filter(item => allowedSet.has(item.id))
+```
+
+### 7.2 Use toSorted() Instead of sort()
+
+```typescript
+// BAD: mutates original array
+const sorted = users.sort((a, b) => a.name.localeCompare(b.name))
+
+// GOOD: creates new array
+const sorted = users.toSorted((a, b) => a.name.localeCompare(b.name))
+```
+
+### 7.3 Early Return from Functions
+
+```typescript
+// BAD: processes all items after finding error
+function validateUsers(users: User[]) {
+  let hasError = false
+  for (const user of users) {
+    if (!user.email) hasError = true
+  }
+  return hasError ? { valid: false } : { valid: true }
+}
+
+// GOOD: returns immediately on first error
+function validateUsers(users: User[]) {
+  for (const user of users) {
+    if (!user.email) return { valid: false, error: 'Email required' }
+  }
+  return { valid: true }
+}
+```
+
+---
+
+## 8. Advanced Patterns
+
+**Impact: LOW**
+
+### 8.1 useEffectEvent for Stable Callbacks
+
+```tsx
+import { useEffectEvent } from 'react'
+
+function useWindowEvent(event: string, handler: () => void) {
+  const onEvent = useEffectEvent(handler)
+  useEffect(() => {
+    window.addEventListener(event, onEvent)
+    return () => window.removeEventListener(event, onEvent)
+  }, [event])
+}
+```
+
+---
+
+## Checklist Before Implementation
+
+- [ ] Independent async operations use Promise.all()
+- [ ] Heavy components use dynamic imports
+- [ ] RSC boundaries pass only needed fields
+- [ ] Suspense boundaries isolate data fetching
+- [ ] No barrel file imports for large libraries
+- [ ] State updates use functional form when depending on current state
+- [ ] Effects have narrow dependencies
+- [ ] Repeated lookups use Set/Map
+
+---
+
+## References
+
+- [React Documentation](https://react.dev)
+- [Next.js Documentation](https://nextjs.org)
+- [SWR Documentation](https://swr.vercel.app)
+- [Vercel Blog: Package Import Optimization](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
+- [Vercel Blog: Dashboard Performance](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)

package/templates/skills/subagents-discipline/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: subagents-discipline
+description: Core engineering principles for implementation tasks
+---
+
+# Implementation Principles
+
+## Rule 0: Read the Bead First
+
+Before implementing anything, **read the bead comments** for context:
+
+```bash
+bd show {BEAD_ID}
+bd comments {BEAD_ID}
+```
+
+The orchestrator's dispatch prompt is automatically logged as a DISPATCH comment on the bead. This contains:
+- The investigation findings
+- Root cause analysis (file, function, line)
+- Related files that may need changes
+- Gotchas and edge cases
+
+**Use this context.** Don't re-investigate. The comments contain everything you need to implement confidently.
+
+If no dispatch or context comments exist, ask the orchestrator to provide context before proceeding.
+
+---
+
+## Rule 1: Look Before You Code
+
+Before writing code that touches external data (API, database, file, config):
+
+1. **Fetch/read the ACTUAL data** - run the command, see the output
+2. **Note exact field names, types, formats** - not what docs say, what you SEE
+3. **Code against what you observed** - not what you assumed
+
+```
+WITHOUT looking first:
+  Assumed: column is "reference_images"
+  Reality: column is "reference_image_url"
+  Result:  Query fails
+
+WITH looking first:
+  Ran: SELECT column_name FROM information_schema.columns WHERE table_name = 'assets';
+  Saw: reference_image_url
+  Coded against: reference_image_url
+  Result: Works
+```
+
+## Rule 2: Test Functionally (Close the Loop)
+
+**Principle: Optimize for the fastest way to verify your work actually works.**
+
+| You built | Fast verification | Slower alternative |
+|-----------|------------------|--------------------|
+| API endpoint | `curl` the endpoint, check response | Write integration test |
+| Database change | Run migration, query the result | Write migration test |
+| Frontend component | Load in browser, interact with it | Write component test |
+| CLI tool | Run the command, check output | Write unit test |
+| Config change | Restart service, verify behavior | N/A — just verify |
+
+**Two strategies:**
+
+1. **User Journey Tests** — Test actual behavior as a user experiences it:
+   ```bash
+   # API: curl with real data
+   curl -X POST localhost:3000/api/users -d '{"name":"test"}' -H "Content-Type: application/json"
+
+   # CLI: run the command
+   bd create "Test" -d "Testing" && bd list
+
+   # Error case: curl with invalid auth
+   curl -X POST localhost:3000/api/users -H "Authorization: Bearer invalid"
+   ```
+
+2. **Component Tests** — Supplement for regression prevention when fast verification isn't possible:
+   - Complex logic with many edge cases
+   - Code that runs in environments you can't easily replicate
+   - Shared libraries used by multiple consumers
+
+**"Close the Loop" principle:** Run the actual thing. Verify it works. Check error cases.
+
+Good: "Curled endpoint with invalid auth, got 401 as expected"
+Bad: "Wrote tests, they compile"
+
+## Rule 3: Use Your Tools
+
+Before claiming you can't fully test:
+
+1. **Check what MCP servers you have access to** - list available tools
+2. **If any tool can help verify the feature works**, use it
+3. **Be resourceful** - browser automation, database inspection, API testing tools
+
+## Rule 4: Log Your Approach (Optional)
+
+If you deviated from the orchestrator's suggestion, found a better path, or made a choice future maintainers might question:
+
+```bash
+bd comment {BEAD_ID} "APPROACH: Used X instead of Y because Z"
+```
+
+When to log:
+- Deviated from the suggested fix
+- Multiple valid solutions, chose one for a specific reason
+- Future maintainers might question the approach
+
+Skip if the code is self-explanatory. This is not enforced.
+
+---
+
+## For Epic Children
+
+If your BEAD_ID contains a dot (e.g., BD-001.2), you're implementing part of a larger feature:
+
+1. **Check for design doc**: `bd show {EPIC_ID} --json | jq -r '.[0].design'`
+2. **Read it if it exists** - this is your contract
+3. **Match it exactly** - same field names, same types, same shapes
+
+---
+
+## Red Flags - Stop and Verify
+
+When you catch yourself thinking:
+- "This should work..." → run it and see
+- "I assume the field is..." → look at the actual data
+- "I'll test it later..." → test it now
+- "It's too simple to break..." → verify anyway

package/templates/ui-constraints.md

@@ -0,0 +1,76 @@
+# UI Constraints
+
+Apply these opinionated constraints when building interfaces.
+
+## Stack
+
+- MUST use Tailwind CSS defaults unless custom values already exist or are explicitly requested
+- MUST use `motion/react` (formerly `framer-motion`) when JavaScript animation is required
+- SHOULD use `tw-animate-css` for entrance and micro-animations in Tailwind CSS
+- MUST use `cn` utility (`clsx` + `tailwind-merge`) for class logic
+
+## Components
+
+- MUST use accessible component primitives for anything with keyboard or focus behavior (`Base UI`, `React Aria`, `Radix`)
+- MUST use the project's existing component primitives first
+- NEVER mix primitive systems within the same interaction surface
+- SHOULD prefer [`Base UI`](https://base-ui.com/react/components) for new primitives if compatible with the stack
+- MUST add an `aria-label` to icon-only buttons
+- NEVER rebuild keyboard or focus behavior by hand unless explicitly requested
+
+## Interaction
+
+- MUST use an `AlertDialog` for destructive or irreversible actions
+- SHOULD use structural skeletons for loading states
+- NEVER use `h-screen`, use `h-dvh`
+- MUST respect `safe-area-inset` for fixed elements
+- MUST show errors next to where the action happens
+- NEVER block paste in `input` or `textarea` elements
+
+## Animation
+
+- NEVER add animation unless it is explicitly requested
+- MUST animate only compositor props (`transform`, `opacity`)
+- NEVER animate layout properties (`width`, `height`, `top`, `left`, `margin`, `padding`)
+- SHOULD avoid animating paint properties (`background`, `color`) except for small, local UI (text, icons)
+- SHOULD use `ease-out` on entrance
+- NEVER exceed `200ms` for interaction feedback
+- MUST pause looping animations when off-screen
+- SHOULD respect `prefers-reduced-motion`
+- NEVER introduce custom easing curves unless explicitly requested
+- SHOULD avoid animating large images or full-screen surfaces
+
+## Typography
+
+- MUST use `text-balance` for headings and `text-pretty` for body/paragraphs
+- MUST use `tabular-nums` for data
+- SHOULD use `truncate` or `line-clamp` for dense UI
+- NEVER modify `letter-spacing` (`tracking-*`) unless explicitly requested
+
+## Layout
+
+- MUST use a fixed `z-index` scale (no arbitrary `z-*`)
+- SHOULD use `size-*` for square elements instead of `w-*` + `h-*`
+
+## Performance
+
+- NEVER animate large `blur()` or `backdrop-filter` surfaces
+- NEVER apply `will-change` outside an active animation
+- NEVER use `useEffect` for anything that can be expressed as render logic
+
+## Design
+
+- NEVER use gradients unless explicitly requested
+- NEVER use purple or multicolor gradients
+- NEVER use glow effects as primary affordances
+- SHOULD use Tailwind CSS default shadow scale unless explicitly requested
+- MUST give empty states one clear next action
+- SHOULD limit accent color usage to one per view
+- SHOULD use existing theme or Tailwind CSS color tokens before introducing new ones
+
+## Accessibility
+
+- MUST meet WCAG AA color contrast (4.5:1 for text, 3:1 for large text/UI)
+- MUST ensure all interactive elements are keyboard accessible
+- SHOULD provide visible focus indicators
+- MUST use semantic HTML elements where appropriate