Create Beads Orchestration

Set up lightweight multi-agent orchestration with git-native task tracking and mandatory code review gates.

CRITICAL: Mandatory 4-Step Workflow

AskUserQuestion(
  questions=[{
    "question": "How should read-only agents (scout, detective, architect, scribe, code-reviewer) be executed?",
    "header": "Providers",
    "options": [
      {"label": "Claude only (Recommended)", "description": "All agents run via Claude Task(). Simpler setup, no external dependencies."},
      {"label": "External providers", "description": "Delegate to Codex CLI (with Gemini fallback). Requires codex login and optional gemini CLI."}
    ],
    "multiSelect": false
  }]
)

git clone --depth=1 https://github.com/AvivK5498/The-Claude-Protocol "${TMPDIR:-/tmp}/beads-orchestration-setup"

# If user selected "Claude only":
python3 "${TMPDIR:-/tmp}/beads-orchestration-setup/bootstrap.py" \
  --project-name "{{PROJECT_NAME}}" \
  --project-dir "{{PROJECT_DIR}}" \
  --claude-only

# If user selected "External providers":
python3 "${TMPDIR:-/tmp}/beads-orchestration-setup/bootstrap.py" \
  --project-name "{{PROJECT_NAME}}" \
  --project-dir "{{PROJECT_DIR}}"

Task(
    subagent_type="discovery",
    prompt="Detect tech stack and create supervisors for this project"
)

rm -rf "${TMPDIR:-/tmp}/beads-orchestration-setup"

Create Beads Orchestration

Set up lightweight multi-agent orchestration with git-native task tracking for Claude Code.

What This Skill Does

This skill bootstraps a complete multi-agent workflow where:

• Orchestrator (you) investigates issues, manages tasks, delegates implementation
• Supervisors (specialized agents) execute fixes in isolated worktrees
• Beads CLI tracks all work with git-native task management
• Hooks enforce workflow discipline automatically

Each task gets its own worktree at .worktrees/bd-{BEAD_ID}/, keeping main clean and enabling parallel work.

Beads Kanban UI

The setup will auto-detect Beads Kanban UI and configure accordingly. If not found, you'll be offered to install it.

Step 0: Detect Setup State (ALWAYS RUN FIRST)

ls .claude/agents/scout.md 2>/dev/null && echo "BOOTSTRAP_COMPLETE" || echo "FRESH_SETUP"

which bead-kanban 2>/dev/null && echo "KANBAN_FOUND" || echo "KANBAN_NOT_FOUND"

AskUserQuestion(
  questions=[
    {
      "question": "Beads Kanban UI not detected. It adds a visual kanban board with dependency graphs and API-driven worktree management. Install it?",
      "header": "Kanban UI",
      "options": [
        {"label": "Yes, install it (Recommended)", "description": "Runs: npm install -g beads-kanban-ui"},
        {"label": "Skip", "description": "Use git worktrees directly. You can install later."}
      ],
      "multiSelect": false
    }
  ]
)

# With Kanban UI:
npx beads-orchestration@latest bootstrap \
  --project-name "{{PROJECT_NAME}}" \
  --project-dir "{{PROJECT_DIR}}" \
  --with-kanban-ui

# Without Kanban UI (git worktrees only):
npx beads-orchestration@latest bootstrap \
  --project-name "{{PROJECT_NAME}}" \
  --project-dir "{{PROJECT_DIR}}"

Task(
    subagent_type="discovery",
    prompt="Detect tech stack and create supervisors for this project"
)

Create Beads Orchestration

Set up lightweight multi-agent orchestration with git-native task tracking for Claude Code.

What This Skill Does

This skill bootstraps a complete multi-agent workflow where:

• Orchestrator (you) investigates issues, manages tasks, delegates implementation
• Supervisors (specialized agents) execute fixes in isolated worktrees
• Beads CLI tracks all work with git-native task management
• Hooks enforce workflow discipline automatically

Each task gets its own worktree at .worktrees/bd-{BEAD_ID}/, keeping main clean and enabling parallel work.

Beads Kanban UI

The setup will auto-detect Beads Kanban UI and configure accordingly. If not found, you'll be offered to install it.

Step 0: Detect Setup State (ALWAYS RUN FIRST)

ls .claude/agents/scout.md 2>/dev/null && echo "BOOTSTRAP_COMPLETE" || echo "FRESH_SETUP"

which bead-kanban 2>/dev/null && echo "KANBAN_FOUND" || echo "KANBAN_NOT_FOUND"

AskUserQuestion(
  questions=[
    {
      "question": "Beads Kanban UI not detected. It adds a visual kanban board with dependency graphs and API-driven worktree management. Install it?",
      "header": "Kanban UI",
      "options": [
        {"label": "Yes, install it (Recommended)", "description": "Runs: npm install -g beads-kanban-ui"},
        {"label": "Skip", "description": "Use git worktrees directly. You can install later."}
      ],
      "multiSelect": false
    }
  ]
)

# With Kanban UI:
npx beads-orchestration@latest bootstrap \
  --project-name "{{PROJECT_NAME}}" \
  --project-dir "{{PROJECT_DIR}}" \
  --with-kanban-ui

# Without Kanban UI (git worktrees only):
npx beads-orchestration@latest bootstrap \
  --project-name "{{PROJECT_NAME}}" \
  --project-dir "{{PROJECT_DIR}}"

Task(
    subagent_type="discovery",
    prompt="Detect tech stack and create supervisors for this project"
)

Implementation Discipline

Core principle: Test the FEATURE, not just the component you built.

Three Rules

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

This catches: field name mismatches, wrong data shapes, missing fields, format differences.

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 Both Levels

Component test catches: logic bugs, edge cases, type errors Feature test catches: integration bugs, auth issues, data flow problems

Both are required. Component test alone is NOT sufficient.

The pattern:

1. Build the thing
2. Component test - verify your piece works in isolation
3. Feature test - verify the integrated feature works end-to-end
4. Only then claim done

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

"I couldn't test the feature" is only valid after exhausting available options.

DEMO Block (Required)

Every completion must include evidence. Code reviewer will verify this.

DEMO:
  COMPONENT:
    Command: [what you ran to test the component]
    Result: [what you observed]

  FEATURE:
    Steps: [how you tested the integrated feature]
    Result: [what you observed - screenshot, output, etc.]

When Full Feature Test Isn't Possible

If you genuinely cannot test end-to-end (long-running job, external service, no browser tools):

DEMO:
  COMPONENT:
    Command: curl localhost:3008/api/endpoint
    Result: 200, returns expected data

  FEATURE: PARTIAL
    Verified: [what you could test]
    Needs human check: [what still needs verification]
    Why: [specific reason - no browser MCP, takes 10+ minutes, requires external service]

Not acceptable reasons for PARTIAL:

• "Server wasn't running" → start it
• "Didn't have test data" → create it
• "Would take too long" → if < 2 minutes, do it

Acceptable reasons:

• No browser/UI automation tools available
• External API with rate limits or costs
• Job takes > 5 minutes to complete
• Requires production data that can't be mocked

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

Design docs ensure all pieces fit together. If you deviate, integration fails.

Completion Checklist

Before marking done:

• Looked at actual data/interfaces before coding (not assumed)
• Component test passes (your piece works in isolation)
• Feature test passes OR documented as PARTIAL with valid reason
• DEMO block included with evidence
• Used available tools to test (checked MCP servers, used what helps)

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

When you're about to say:

• "Done!" / "Fixed!" / "Should work now!" → show the DEMO first

The Bottom Line

Component test passing ≠ feature works
Curl returning 200 ≠ UI displays correctly
TypeScript compiles ≠ user can use it

Test the feature like a user would use it. Then show evidence. Then claim done.

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.

// 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

// 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

// 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

// 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

// 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

// 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

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

// 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

// 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()

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

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

// 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

// 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

// 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

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

// 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

.message-item {
  content-visibility: auto;
  contain-intrinsic-size: 0 80px;
}

6.2 Hoist Static JSX Elements

// 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

// 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

// 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()

// 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

// 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

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
• Next.js Documentation
• SWR Documentation
• Vercel Blog: Package Import Optimization
• Vercel Blog: Dashboard Performance

Implementation Principles

Rule 0: Read the Bead First

Before implementing anything, read the bead comments for context:

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.

Two strategies:

1. User Journey Tests — Test actual behavior as a user experiences it:

   # 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:

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