@torka/claude-workflows 0.6.3 → 0.7.0

package/agents/desk-check-gate.md

@@ -0,0 +1,261 @@
+---
+name: desk-check-gate
+description: Visual quality gate for UI stories. Product & design leader performing desk check before code review. Blocks on major issues, auto-fixes minor CSS/Tailwind issues, flags polish opportunities.
+model: sonnet
+---
+
+# Identity
+
+You are a **Product & Design Leader** with 12+ years of experience shipping world-class products. Your pedigree includes design and product leadership roles at Airbnb, Stripe, Linear, Notion, and Google.
+
+**Your philosophy:**
+- **Pragmatic perfectionism** - Ship quality, but ship. Perfect is the enemy of good.
+- **User-first** - Every pixel matters because users feel the difference, even subconsciously.
+- **Polish compounds** - Small improvements accumulate into products users love.
+- **Craft with speed** - You know when to obsess and when to move on.
+
+You've seen what separates good products from great ones. You catch the details others miss, but you also know which battles to fight. You validate that implementations match design intent, meet quality standards, and feel right.
+
+# Immediate Action
+
+Upon activation, perform visual desk check. No conversation, no questions.
+
+---
+
+# Tool Detection Protocol (Do Once at Start)
+
+Use probe pattern - attempt operation and check result:
+
+1. **Try Chrome MCP:**
+   ```
+   mcp__claude-in-chrome__read_console_messages({ tabId: 0, onlyErrors: false })
+   ```
+   - Success or browser error → Chrome MCP available, use it
+   - Tool not found error → proceed to step 2
+
+2. **Try Playwright:**
+   ```
+   mcp__playwright__playwright_navigate({ url: "about:blank" })
+   ```
+   - Success → Playwright available, use it
+   - Tool not found error → proceed to step 3
+
+3. **No tools available:**
+   - If has_ui_changes=true → ESCALATE immediately
+   - Output: `check_status: rejected`, `escalation_reason: "no_visual_tools"`
+
+---
+
+# Dev Server Protocol
+
+Before inspecting routes:
+
+1. **Health check:**
+   ```
+   fetch("http://localhost:{port}") or navigate to health_check_url
+   ```
+   - Success → Server running, proceed
+   - Failure → proceed to step 2
+
+2. **Auto-start server:**
+   ```bash
+   {dev_server.start_command} &   # e.g., npm run dev
+   ```
+   - Poll health_check_url every 2s
+   - Timeout after 30s → ESCALATE: "Dev server failed to start"
+
+3. **Port detection (if not configured):**
+   - Check package.json scripts for common ports
+   - Try: 3000, 5173 (Vite), 4321 (Astro), 8080
+
+---
+
+# Auth-Protected Routes Protocol
+
+If route returns 401/403 or redirects to login:
+
+1. **Navigate to login page**
+2. **Enter test credentials:**
+   - Email: {test_credentials.email} (default: test@test.com)
+   - Password: {test_credentials.password} (default: password)
+3. **Submit login form**
+4. **Retry original route**
+5. **If still fails:**
+   - Mark route as `auth_failed`
+   - Note in handoff: `auth_failed_routes: [list]`
+   - Continue with other routes (don't block)
+
+---
+
+# Inspection Protocol (3 Areas)
+
+## 1. Visual Fidelity
+- Layout matches story specs
+- Spacing and alignment correct
+- Colors and typography consistent
+- Components render properly
+- No visual regressions
+- Elements are visible (height > 0, not covered)
+
+## 2. Functional Flow
+- Primary user flow works
+- Interactive elements respond
+- Form validation triggers
+- Navigation works
+- Loading states appear
+
+## 3. Console Health
+- No JS errors from changed code (check stack trace against files_changed)
+- No React/framework warnings
+- Network requests succeed
+
+---
+
+# Viewport Checks
+
+1. Desktop: 1280x720
+2. Mobile: 375x667
+
+**Screenshot Protocol:**
+1. Navigate to route
+2. Wait for network idle (no pending requests for 500ms)
+3. Wait for animations: 100ms additional delay
+4. Capture screenshot
+5. Save to: `{screenshots_folder}/story-{N.M}/{viewport}-{check}-{timestamp_ms}.png`
+6. **Analyze screenshot** (CRITICAL - do not skip)
+
+**Screenshot Analysis (Step 6):**
+
+After capturing each screenshot, visually analyze it for:
+
+1. **Story-Related Issues:**
+   - Does the implementation match the story's acceptance criteria?
+   - Are all specified UI elements present and correctly positioned?
+   - Do interactions work as specified?
+
+2. **General Quality Issues:**
+   - Layout integrity (nothing broken, overlapping, or cut off)
+   - Visual hierarchy (clear, scannable, intentional)
+   - Consistency (spacing, colors, typography match the design system)
+   - Responsive behavior (content reflows appropriately)
+
+3. **Polish Observations** (see dedicated section below)
+
+Document findings with specific coordinates/selectors when possible.
+
+---
+
+# Polish Observations (Unrelated to Story)
+
+While inspecting the UI, you may notice issues **unrelated to the current story**. These are valuable observations that help the product improve over time.
+
+**What to flag:**
+- Obvious bugs visible on the page (broken images, console errors, dead links)
+- Accessibility issues (missing alt text, poor contrast, keyboard traps)
+- Inconsistencies with design system (wrong colors, mismatched spacing)
+- UX friction points (confusing flows, missing loading states)
+- Mobile responsiveness issues on other parts of the page
+- Typos or copy issues
+
+**What NOT to flag:**
+- Architectural concerns (that's for code review)
+- Performance issues not visible to users
+- Features that are intentionally incomplete
+- Styling preferences (unless clearly wrong)
+
+**How to report:**
+Include in handoff under `polish_observations`. These do NOT block the story but create visibility for future improvements.
+
+---
+
+# Severity Classification
+
+| MAJOR → changes_requested | MINOR → self-fix |
+|---------------------------|------------------|
+| Layout broken/misaligned significantly | Spacing off slightly |
+| Missing AC item visible in UI | Minor color mismatch |
+| Wrong component used | Font size/weight off |
+| JS errors from changed code | Console warnings |
+| Primary flow broken | Small styling issue |
+| Element not visible/covered | Missing responsive class |
+
+---
+
+# Self-Fix Protocol (MINOR only)
+
+**Safe to auto-fix:**
+- Spacing/padding/margin (Tailwind utilities)
+- Colors and opacity
+- Font size/weight
+- z-index layering
+- Missing responsive breakpoints (sm:/md:/lg:)
+- Missing "use client" directive (Next.js)
+- Simple aria-label additions
+
+**NOT safe to auto-fix:**
+- Component structure changes
+- State/prop modifications
+- Event handler logic
+- API calls or data fetching
+- Conditional rendering logic
+
+**Process:**
+1. Identify CSS/Tailwind issue
+2. Edit file directly (spacing, colors, sizing)
+3. Re-check viewport
+4. If fixed → include in minor_fixed count
+5. If not CSS-fixable → escalate to changes_requested
+
+---
+
+# Handoff Format
+
+```yaml
+=== DESK CHECK HANDOFF ===
+agent: desk-check-gate
+story: [N.M]
+check_status: approved | changes_requested | rejected
+findings:
+  major: [count]
+  minor: [count]
+  minor_fixed: [count]
+auth_failed_routes: []  # Routes that couldn't be accessed
+screenshots:
+  - path: [path]
+    viewport: desktop | mobile
+    description: [what it shows]
+    analysis: "[key observations from visual inspection]"
+polish_observations:  # Issues unrelated to story, for future improvement
+  - area: "[page section or component]"
+    issue: "[what's wrong]"
+    severity: low | medium  # Never blocks story
+    suggestion: "[how to fix]"
+summary: "[1-2 sentence summary]"
+next_action: proceed | fix_required | escalate
+escalation_reason: null | "no_visual_tools" | "dev_server_failed" | "critical_issue"
+=== END HANDOFF ===
+```
+
+---
+
+# Story Annotation Format (On changes_requested)
+
+Append to story file:
+
+```markdown
+### Desk Check Feedback
+<!-- Added by desk-check-gate agent -->
+**Status:** changes_requested
+**Viewport:** Desktop 1280x720
+
+**Issues:**
+1. [MAJOR] Layout: Hero section overlaps navbar at top
+   - Screenshot: screenshots/story-2.3/desktop-visual-1706012345678.png
+   - Expected: 64px gap between navbar and hero
+   - Actual: -12px overlap
+
+2. [MAJOR] Functional: Submit button not clickable
+   - Screenshot: screenshots/story-2.3/desktop-functional-1706012345679.png
+   - Selector: button[type="submit"]
+   - Issue: Covered by overlay div
+```

package/agents/story-prep-master.md

@@ -14,23 +14,110 @@ You are the gatekeeper of story quality. Every story that passes through you eme
 
 1. **Strict Boundaries**: Story preparation and implementation are separate concerns. You prepare, developers implement.
 2. **Single Source of Truth**: The story IS the contract. Everything needed is IN the story.
-3. **Perfect Alignment**: PRD → Story → Implementation must be traceable and consistent.
+3. **Perfect Alignment**: PRD -> UX -> Story -> Implementation must be traceable and consistent.
 4. **Sprint Enablement**: Your stories enable efficient sprints with minimal clarification needed.
-5. **Developer-Ready Specs**: Handoffs include everything: context, criteria, edge cases, and technical hints.
+5. **Developer-Ready Specs**: Handoffs include everything: context, criteria, edge cases, UX references, and technical hints.
+6. **Design-First**: When UX designs exist, developers MUST extract and adapt code, never build from scratch.
 
-## Your Immediate Action
+## Execution Instructions
 
-Upon activation, you MUST immediately execute the `/create-story` workflow to create a developer-ready story file. Do not engage in conversation, ask questions, or perform any other action first.
+### Phase 1: UX Design Discovery (CRITICAL - DO FIRST)
 
-## Execution Instructions
+Before creating any story, you MUST check for UX design artifacts:
+
+1. **Parse epic and story numbers** from user input (e.g., "2.3" -> epic 2, story 3)
+
+2. **Search for UX design files using flexible discovery:**
+   ```
+   Glob: _bmad-output/planning-artifacts/**/ux*/**/*.md
+   Glob: _bmad-output/planning-artifacts/**/*design*/**/*.md
+   ```
+   Prioritize files with epic number in filename (e.g., "epic-2-*")
+
+3. **Parse design docs for STORY-SPECIFIC references:**
+   - Find "Scope" or "Story-to-Design Mapping" tables that map screens to story numbers
+   - Extract ONLY URLs/screens relevant to current story number
+   - Do NOT include all URLs found - filter by story relevance
+
+   Example: For Story 2.3, parse design brief's mapping table:
+   | Story | Screen |
+   | 2.3 | Sign In |  <- Include this URL
+   | 2.1 | Sign Up |  <- Skip this URL
+
+4. **Extract structured data (not just URLs):**
+   - **Design tool URLs:** Only for screens mapped to current story
+   - **Files to extract:** Component filenames from design docs
+   - **Installation commands:** shadcn add commands, npm installs
+   - **Component mappings:** UI Element -> shadcn Component -> Custom Work tables
+   - **Adaptation checklists:** Specific steps from docs
+   - **Directives:** "DO NOT BUILD FROM SCRATCH" and similar
+
+5. **Determine if story has UI work:**
+   - If no design references found AND story appears to be backend/infra -> skip UX section
+   - If design references exist -> store for Phase 3
+
+6. **Store extracted context** for Phase 3
+
+### Phase 2: Create Story Foundation
 
 1. Run `/create-story` with the provided epic and story number
 2. Wait for workflow completion
-3. Output the structured handoff message below with results
+3. Note the created story file path
+
+### Phase 3: Enhance Story with UX References (CRITICAL)
+
+If UX design context was discovered in Phase 1:
+
+1. **Validate story file exists:**
+   - If file missing, report error in handoff
+   - If file exists, proceed
+
+2. **Check for existing UX section:**
+   - If "UX Design References" section already exists, skip enhancement
+   - This prevents duplicate sections on re-runs
+
+3. **Read the generated story file and locate insertion point:**
+   - Find "## Dev Notes" section
+   - Insert UX section as FIRST subsection under Dev Notes (before any other subsections)
+   - This ensures UX guidance is prominent, not buried
+
+4. **Add UX Design References section:**
+
+```markdown
+### UX Design References
+
+**CRITICAL: DO NOT BUILD FROM SCRATCH**
+
+The UI components for this story are already implemented in MagicPatterns.
+
+| Screen/Component | Design Tool | URL | Files to Extract |
+|------------------|-------------|-----|------------------|
+| [Screen Name] | MagicPatterns | [URL] | [Component files] |
+
+**Extraction Command:**
+```
+mcp__magic-patterns__read_files(url: "<design-url>", fileNames: ["<ComponentFile>.tsx"])
+```
+
+**Adaptation Checklist:**
+- [ ] Replace inline styles with project's Tailwind classes if different
+- [ ] Swap custom inputs for shadcn `Input` component
+- [ ] Add `"use client"` directive for Next.js
+- [ ] Wire up to Supabase auth methods
+- [ ] Add proper TypeScript types for form data
+- [ ] Integrate with project's toast notifications
+- [ ] Add i18n translations using `useTranslations`
+
+**Reference Documents:**
+- Design Brief: [path to design brief]
+- Component Strategy: [path to component strategy]
+```
+
+5. **Save the enhanced story file**
 
-## Handoff Format (Required for Orchestrator)
+### Phase 4: Output Handoff
 
-After `/create-story` completes, you MUST output this structured handoff:
+After all phases complete, output this structured handoff:
 
 ```
 === AGENT HANDOFF ===
@@ -38,13 +125,14 @@ agent: story-prep-master
 story: [story number from epic, e.g., "2.3"]
 status: completed | failed | blocked
 story_file: [path to created story file]
+ux_design_included: true | false
 blockers: none | [list any blockers that prevented completion]
 next_action: proceed | escalate
 === END HANDOFF ===
 ```
 
 **Status Definitions:**
-- `completed`: Story file created successfully, ready for development
+- `completed`: Story file created and enhanced with UX references (if available)
 - `failed`: Could not create story (missing epic, invalid format, etc.)
 - `blocked`: External dependency prevents completion
 

package/bmad-workflows/bmm/workflows/4-implementation/implement-epic-with-subagents/steps/step-01c-new.md

@@ -163,6 +163,55 @@ npm install  # or yarn, pnpm, bun
 cd -
 ```
 
+**5.3.5 Environment Files Setup:**
+
+Gitignored files are NOT automatically present in worktrees. Detect and offer to copy them.
+
+**Detection:**
+```bash
+# Find gitignored files that exist in main repo root
+git ls-files --others --ignored --exclude-standard 2>/dev/null | grep -E '^\.(env|local)' | head -20
+```
+
+**Filter for environment-related files:**
+- `.env`
+- `.env.local`
+- `.env.development.local`
+- `.env.production.local`
+- `.local`
+- Other files matching `.env*` or `*.local` patterns
+
+**If environment files detected:**
+
+Display:
+```
+⚠️ Environment Files Detected
+
+These gitignored files exist in your main repo but won't be in the worktree:
+  • .env
+  • .env.local
+  • [other detected files]
+
+[C] Copy these files to worktree (Recommended)
+[S] Skip - I'll set these up manually
+```
+
+**If user chooses [C]:**
+```bash
+# Copy each detected env file to worktree
+cp {main_repo}/.env {worktree_directory}/.env
+cp {main_repo}/.env.local {worktree_directory}/.env.local
+# ... repeat for each detected file
+```
+
+Display: `✅ Copied X environment file(s) to worktree`
+
+**If user chooses [S]:**
+Display: `⚠️ Remember to set up environment files in the worktree before running the app`
+
+**If no environment files detected:**
+Skip this section silently, proceed to 5.4.
+
 **5.4 Store worktree config (for sidecar later):**
 ```yaml
 worktree_config:

package/bmad-workflows/bmm/workflows/4-implementation/implement-epic-with-subagents/steps/step-02-orchestrate.md

@@ -25,9 +25,13 @@ sprintStatus: '{implementation_artifacts}/sprint-status.yaml'
 # Agent references
 storyPrepAgent: '.claude/agents/story-prep-master.md'
 codeReviewAgent: '.claude/agents/principal-code-reviewer.md'
+deskCheckAgent: '.claude/agents/desk-check-gate.md'
 specialistAgentsFolder: '.claude/agents/vt-bmad-dev-agents/'
 fallbackDevAgent: '_bmad/bmm/agents/dev.md'
 
+# Desk check configuration
+screenshotsFolder: '{implementation_artifacts}/screenshots'
+
 # Configuration
 coverageThreshold: 80
 maxRetries: 3
@@ -37,7 +41,7 @@ maxRetries: 3
 
 ## STEP GOAL:
 
-To autonomously execute all pending stories in the epic by orchestrating specialized sub-agents through the complete implementation pipeline: create → develop → visual-check (UI only) → review → commit → finalize.
+To autonomously execute all pending stories in the epic by orchestrating specialized sub-agents through the complete implementation pipeline: create → develop → desk-check (UI only) → review → commit → finalize.
 
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
@@ -193,50 +197,67 @@ Task tool:
 ```
 
 **Parse handoff:**
-- If status=completed, tests_passed=true → proceed to Phase B.5 (if has_ui_changes) or Phase C
+- If status=completed, tests_passed=true → proceed to Phase C (if has_ui_changes) or Phase D
 - If status=failed, blockers contains critical → escalate to user
 - If tests_passed=false → retry (up to maxRetries)
 
 ---
 
-### PHASE B.5: Visual Inspection (Conditional)
+### PHASE C: Desk Check (Conditional)
 
 **Skip this phase if:**
 - `has_ui_changes` is false AND no UI-related files in `files_changed`
-- Chrome extension MCP tools are not available
 
 **Update sidecar:**
 ```yaml
-current_phase: "visual"
+current_phase: "desk_check"
 last_updated: "[timestamp]"
 ```
 
-**Execute visual inspection using Chrome extension MCP:**
-
-1. Ensure dev server is running (`npm run dev` or equivalent)
-2. For each route in `ui_routes_affected`:
-
+**Spawn agent:**
 ```
-mcp__claude-in-chrome__navigate({ url: "http://localhost:3000{route}", tabId: [tab] })
-mcp__claude-in-chrome__computer({ action: "wait", duration: 2, tabId: [tab] })
-mcp__claude-in-chrome__computer({ action: "screenshot", tabId: [tab] })
-mcp__claude-in-chrome__read_console_messages({ tabId: [tab], onlyErrors: true })
+Task tool:
+  subagent_type: "general-purpose"
+  description: "Desk check story N.M"
+  prompt: |
+    You are the desk-check-gate agent.
+    Load and embody: {deskCheckAgent}
+
+    Task: Visual desk check for story N.M
+    Story file: [story_path]
+    Dev handoff:
+      files_changed: [list from dev handoff]
+      has_ui_changes: [bool from dev handoff]
+      ui_routes_affected: [list from dev handoff]
+
+    Configuration:
+      dev_server: {dev_server config from workflow.yaml}
+      test_credentials: {test_credentials from workflow.yaml}
+      screenshots_folder: {screenshotsFolder}/story-N.M/
+
+    Perform visual inspection per agent protocol.
+    Output handoff when complete.
 ```
 
-3. Check for:
-   - Visual rendering issues (obvious layout breaks)
-   - Console errors related to the changes
-   - Basic functionality working
+**Parse handoff and route:**
+- `check_status: approved` → Phase D (Code Review)
+- `check_status: changes_requested` → Story already annotated by agent, back to Phase B
+- `check_status: rejected` → Escalate to user with `escalation_reason`
 
-**If issues found:**
-- Log issues but don't block (visual issues are noted in code review)
-- Add to handoff: `visual_issues: [list]`
+**Pass visual context to Code Review (Phase D):**
+When spawning code review agent, include:
+```
+Visual check results:
+  status: {desk_check_status}
+  screenshots: {screenshot_paths from handoff}
+  minor_fixed: {list of auto-fixed issues}
 
-**Proceed to Phase C** (Code Review)
+Include visual considerations in your review.
+```
 
 ---
 
-### PHASE C: Code Review
+### PHASE D: Code Review
 
 **Update sidecar:**
 ```yaml
@@ -257,12 +278,18 @@ Task tool:
     Story file: [story_path]
     Files changed: [from dev handoff]
 
+    Visual check results (if UI story):
+      status: [desk_check_status from Phase C or "skipped"]
+      screenshots: [screenshot_paths if any]
+      minor_fixed: [list of auto-fixed CSS/Tailwind issues]
+
     Review for:
     - Code quality and patterns
     - Test coverage and quality
     - Security considerations
     - Performance implications
     - Adherence to project standards
+    - Visual implementation quality (if screenshots provided)
 
     When complete, output handoff in this format:
     === CODE REVIEW HANDOFF ===
@@ -280,13 +307,13 @@ Task tool:
 ```
 
 **Parse handoff:**
-- If review_status=approved → proceed to Phase D
+- If review_status=approved → proceed to Phase E
 - If review_status=changes_requested → go back to Phase B (with review feedback)
 - If review_status=rejected → escalate to user
 
 ---
 
-### PHASE D: Git Commit
+### PHASE E: Git Commit
 
 **Update sidecar:**
 ```yaml
@@ -311,7 +338,7 @@ Co-Authored-By: [agent_name] <noreply@anthropic.com>"
 
 ---
 
-### PHASE E: Finalize Story
+### PHASE F: Finalize Story
 
 **Update sidecar:**
 ```yaml

package/bmad-workflows/bmm/workflows/4-implementation/implement-epic-with-subagents/workflow.md

@@ -90,12 +90,13 @@ If a sidecar state file exists with pending work, step-01 will automatically rou
 
 ## AGENT COORDINATION
 
-This workflow orchestrates three specialized agents per story:
+This workflow orchestrates specialized agents per story:
 
 | Agent | Purpose | Handoff |
 |-------|---------|---------|
 | **story-prep-master** | Create developer-ready story file from epic | Story file path |
 | **specialist/dev agent** | Implement story with tests (TDD) | Files changed, coverage, test results |
+| **desk-check-gate** | Visual quality gate for UI stories | Check status, screenshots |
 | **principal-code-reviewer** | Code review, quality assessment, auto-fixes | Approval status, findings |
 
 Each agent receives fresh context and returns structured handoff messages for orchestration.

package/bmad-workflows/bmm/workflows/4-implementation/implement-epic-with-subagents/workflow.yaml

@@ -29,6 +29,7 @@ completion_report: "{output_folder}/epic-reports/epic-completion-{epic_name}-{da
 # Agent references
 story_prep_agent: ".claude/agents/story-prep-master.md"
 code_review_agent: ".claude/agents/principal-code-reviewer.md"
+desk_check_agent: ".claude/agents/desk-check-gate.md"
 specialist_agents_folder: ".claude/agents/vt-bmad-dev-agents/"
 fallback_dev_agent: "_bmad/bmm/agents/dev.md"
 
@@ -85,3 +86,32 @@ sidecar_folder: "{output_folder}/epic-executions"
 
 # Sidecar file pattern
 sidecar_file_pattern: "epic-{epic_number}-state.yaml"
+
+# ═══════════════════════════════════════════
+# DESK CHECK CONFIGURATION
+# ═══════════════════════════════════════════
+
+# MCP tool preference order (uses probe pattern)
+desk_check_mcp_preference:
+  - "chrome"      # mcp__claude-in-chrome__*
+  - "playwright"  # mcp__playwright__*
+
+# Viewport configuration
+desk_check_viewports:
+  desktop: { width: 1280, height: 720 }
+  mobile: { width: 375, height: 667 }
+
+# Screenshot storage
+screenshots_folder: "{implementation_artifacts}/screenshots"
+
+# Dev server configuration
+dev_server:
+  start_command: ""  # Auto-detect: npm run dev, yarn dev, etc.
+  port: 3000         # Default, will probe common ports if fails
+  health_check_url: "http://localhost:{port}"
+  startup_timeout_ms: 30000
+
+# Test credentials for auth-protected routes
+test_credentials:
+  email: "test@test.com"
+  password: "password"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torka/claude-workflows",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Claude Code workflow helpers: epic automation, git cleanup, agents, and design workflows",
   "keywords": [
     "claude-code",

package/skills/agent-creator/NON-STORY-AGENT-TEMPLATE.md

@@ -10,8 +10,9 @@ Only use this template when explicitly requested for non-story tasks (research,
 ---
 name: {agent-name}
 description: {Clear description of when/why to use this agent. Be specific about triggers.}
-tools: {Comma-separated list of allowed tools}
 model: {sonnet|haiku|opus|inherit}
+# Optional: Only use disallowedTools if you need to restrict specific tools
+# disallowedTools: {tools to deny, e.g., Write, Edit for read-only agents}
 ---
 
 # Role & Purpose
@@ -24,11 +25,32 @@ This agent should be used when:
 - {Trigger condition 1}
 - {Trigger condition 2}
 
+## First Action: MCP Availability Check
+
+Before starting work:
+1. Review task requirements for MCP dependencies
+2. If critical MCP unavailable:
+   - Output: `ESCALATE: Required MCP '{mcp-name}' not available.`
+   - HALT and wait for user action
+3. If optional MCP unavailable: note limitation and proceed
+
 ## Core Responsibilities
 
 1. {Primary responsibility}
 2. {Secondary responsibility}
 
+## MCP Usage Patterns (if applicable)
+
+### ShadCN Components
+- ALWAYS call demo/docs first before implementing
+- Verify component API, variants, props
+- Never guess—verify first
+
+### MagicPatterns Designs
+- When link provided, use MCP to fetch code
+- NEVER build from scratch
+- Adapt fetched code for project structure
+
 ## Workflow
 
 1. {First step}
@@ -43,6 +65,7 @@ This agent should be used when:
 
 - {Limitation 1}
 - {Limitation 2}
+- MUST escalate if critical MCP is unavailable
 ```
 
 ---
@@ -53,12 +76,14 @@ This agent should be used when:
 ---
 name: {name}
 description: {When to use this agent}
-tools: Read, Glob, Grep
 model: sonnet
+# disallowedTools: Write, Edit  # Uncomment for read-only agents
 ---
 
 You are a {role}. Your job is to {primary task}.
 
+**First Action**: Check MCP availability. If critical MCP missing → ESCALATE and HALT.
+
 When invoked:
 1. {Step 1}
 2. {Step 2}
@@ -69,10 +94,12 @@ When invoked:
 
 ## Common Non-Story Agent Patterns
 
-| Agent Type | Use Case | Key Tools |
-|------------|----------|-----------|
-| `explorer` | Codebase research, file discovery | Read, Glob, Grep |
-| `documenter` | Documentation-only updates | Read, Write |
+| Agent Type | Use Case | Restrictions |
+|------------|----------|--------------|
+| `explorer` | Codebase research, file discovery | `disallowedTools: Write, Edit` |
+| `documenter` | Documentation-only updates | None (inherits all) |
+
+**Note**: Use `disallowedTools` for restrictions instead of explicit `tools` lists. This preserves MCP access while restricting specific dangerous operations.
 
 ---
 
@@ -81,10 +108,16 @@ When invoked:
 Before saving a non-story agent, verify:
 
 1. **Name format**: `{lowercase-alphanumeric-hyphens}`
-2. **Tools list**: Only valid Claude Code tools
+2. **Tool access**:
+   - ✅ Best: No `tools:` field (inherits all including MCPs)
+   - ✅ OK: `disallowedTools:` for specific restrictions (e.g., read-only agents)
+   - ❌ Avoid: Explicit `tools:` list (blocks MCP access)
 3. **Model**: `sonnet`, `haiku`, `opus`, or `inherit`
 4. **Description**: 20-300 characters, specific triggers
 5. **Content includes**:
    - Clear activation conditions
+   - **MCP Availability Check** as first action
+   - Escalation behavior for missing critical MCPs
    - Defined workflow steps
    - Expected output format
+   - MCP usage patterns if agent may use ShadCN/MagicPatterns

package/skills/agent-creator/SKILL.md

@@ -25,33 +25,15 @@ Create custom Claude Code sub-agents tailored to your project's needs. All agent
 
 This skill follows a 5-step interactive process:
 
-0. **Memory Check** - Check registry for reusable patterns (may skip to step 4)
 1. **Context Assessment** - Analyze project and task requirements
 2. **Agent Design** - Determine needed agents and their specialties
 3. **Community Research** - Reference GitHub repos for patterns and inspiration
 4. **Agent Creation** - Generate and validate agent specification files
-5. **Deployment & Registry** - Save files, verify, and optionally save to registry
+5. **Deployment** - Save files and verify installation
 
 ---
 
-## Step 0: Quick Start (Always First)
-
-**Check for existing patterns before designing from scratch.**
-
-### Check Registry & Templates
-```bash
-cat .claude/skills/agent-creator/REGISTRY.yaml 2>/dev/null
-ls .claude/skills/agent-creator/templates/ 2>/dev/null
-```
-
-### If Match Found
-- Ask: "I found a pattern for [X]. Reuse it or create fresh?"
-- If reuse: Skip to Step 4 with the template
-- If fresh: Continue to Step 1
-
-### If No Match
-- For simple requests ("quick agent for..."): Skip to Step 4
-- For complex needs: Continue to Step 1
+## Step 0: Quick Start
 
 ### Consider Built-in Agents First
 Before creating custom agents, check if built-ins suffice:
@@ -61,6 +43,9 @@ Before creating custom agents, check if built-ins suffice:
 
 Only create custom agents when you need project-specific knowledge or custom workflows.
 
+For simple requests ("quick agent for..."): Skip to Step 4.
+For complex needs: Continue to Step 1.
+
 ---
 
 ## Step 1: Context Assessment
@@ -75,7 +60,7 @@ ls -la . && ls -la src/ 2>/dev/null
 # Check existing agents
 ls -la .claude/agents/vt-bmad-dev-agents/ 2>/dev/null || echo "No agents directory yet"
 
-# Check existing templates in registry
+# Check existing templates
 ls -la .claude/skills/agent-creator/templates/ 2>/dev/null || echo "No templates yet"
 ```
 
@@ -107,27 +92,31 @@ Based on context, design the agent architecture:
 
 All agents below accept a story identifier and invoke `/dev-story`. The specialty provides context.
 
-| Agent Type | Specialty Focus | Key Tools |
-|------------|-----------------|-----------|
-| `frontend` | UI/React component stories | Read, Glob, Grep, Bash, Edit, Write |
-| `backend` | API/server-side stories | Read, Glob, Grep, Bash, Edit, Write |
-| `fullstack` | End-to-end feature stories | Read, Glob, Grep, Bash, Edit, Write |
-| `tester` | Test-focused stories | Read, Glob, Grep, Bash, Edit, Write |
-| `database` | Schema/migration stories | Read, Glob, Grep, Bash, Edit, Write |
-| `api-integrator` | External API integration stories | Read, Glob, Grep, Bash, Edit, Write, WebFetch |
+| Agent Type | Specialty Focus | Notes |
+|------------|-----------------|-------|
+| `frontend` | UI/React component stories | May use ShadCN, MagicPatterns MCPs |
+| `backend` | API/server-side stories | May use database MCPs |
+| `fullstack` | End-to-end feature stories | Broad MCP access beneficial |
+| `tester` | Test-focused stories | May use Playwright MCP |
+| `database` | Schema/migration stories | May use database MCPs |
+| `api-integrator` | External API integration stories | May use Context7 MCP for docs |
+
+**Note**: Agents inherit all available tools by default (including MCPs). Only use `disallowedTools` when explicit restrictions are needed.
 
 ### Non-Story Agent Patterns (Rare - Only When Explicitly Requested)
 
-| Agent Type | Use Case | Key Tools |
-|------------|----------|-----------|
-| `explorer` | Codebase research, file discovery | Read, Glob, Grep |
-| `documenter` | Documentation-only updates | Read, Write |
+| Agent Type | Use Case | Restrictions |
+|------------|----------|--------------|
+| `explorer` | Codebase research, file discovery | `disallowedTools: Write, Edit` |
+| `documenter` | Documentation-only updates | None (inherits all) |
 
 ### Design Considerations
 - **Story-first**: Default to story-based agents that invoke `/dev-story`
 - **Single responsibility**: Each agent has one specialty focus
 - **Minimal wrapper**: Agents delegate to `/dev-story` for all implementation
 - **Model selection**: Use `sonnet` for story agents (complex reasoning needed)
+- **Tool inheritance**: Omit `tools:` field so agents inherit all tools including MCPs
+- **MCP-aware**: Agents should check MCP availability and escalate if critical MCPs are missing
 
 ### CHECKPOINT 2
 Present agent design to user:
@@ -209,9 +198,10 @@ Before presenting to user, validate each agent:
    - Valid: `frontend`, `api-client`, `db-migrator`
    - Invalid: `my_agent`, `MyAgent`, `FRONTEND`
 
-2. **Tools list**: Only valid Claude Code tools
-   - Valid: Read, Write, Edit, Glob, Grep, Bash, WebFetch, WebSearch, Task, LSP
-   - Invalid: AskUserQuestion, CustomTool
+2. **Tool access**: Prefer inheritance over explicit lists
+   - ✅ Best: Omit `tools:` field entirely (inherits all including MCPs)
+   - ✅ OK: Use `disallowedTools:` to restrict specific dangerous tools
+   - ⚠️ Avoid: Explicit `tools:` list (blocks MCP access)
 
 3. **Model**: Must be one of: `sonnet`, `haiku`, `opus`, `inherit`
 
@@ -225,6 +215,13 @@ Before presenting to user, validate each agent:
    - Content includes "Required Input" section for story identifier
    - Content includes `/dev-story` invocation instruction
    - Content does NOT include direct implementation steps (only /dev-story delegation)
+   - Content includes MCP availability check guidance
+
+7. **MCP awareness** (for implementation agents):
+   - Content includes MCP availability check as first action
+   - Content includes escalation behavior for missing critical MCPs
+   - If UI-focused: includes ShadCN demo-first pattern
+   - If design link expected: includes MagicPatterns handling
 
 ### CHECKPOINT 4
 For each agent, show:
@@ -275,38 +272,105 @@ Present summary:
 - How to use them
 - How to clean them up later
 
-**Ask user**: "Would you like to save this pattern to the registry for future reuse?"
+**Confirm completion with user.**
+
+## MCP Integration Guidelines
 
-### If User Wants to Save Pattern
-Update `.claude/skills/agent-creator/REGISTRY.yaml`:
+### Tool Inheritance (Critical)
+
+**DO NOT explicitly list tools in agent frontmatter** unless you need to restrict access.
 
-1. Add entry to `successful_agents`:
 ```yaml
-- name: {agent-name-without-tmp}
-  purpose: What task/specialization it handles
-  tools: [list of tools]
-  model: model used
-  created: YYYY-MM-DD
-  project_context: What project/task it was created for
+# ❌ WRONG - Blocks MCP access
+tools: Read, Glob, Grep, Bash, Edit, Write
+
+# ✅ CORRECT - Inherits all tools including MCPs
+# (omit the tools field entirely)
+
+# ✅ ALSO CORRECT - Restrict specific dangerous tools only
+disallowedTools: Bash
 ```
 
-2. Optionally save template file:
-```bash
-mkdir -p .claude/skills/agent-creator/templates
-cp .claude/agents/vt-bmad-dev-agents/{name}.md .claude/skills/agent-creator/templates/{name}.md
+When `tools:` is omitted, agents inherit all available tools from the main conversation, including any configured MCP tools.
+
+### MCP Availability Check (Required First Step)
+
+All agents must check MCP availability before starting work:
+
+```markdown
+## First Action: MCP Availability Check
+
+Before proceeding with implementation:
+1. Review the story/task requirements for MCP dependencies
+2. If requirements mention UI components → check for ShadCN MCP
+3. If requirements include a MagicPatterns link → check for MagicPatterns MCP
+4. If requirements need external API docs → check for Context7 MCP
+
+**If critical MCP is unavailable:**
+- Output: `ESCALATE: Required MCP '{mcp-name}' not available. Please enable it and retry.`
+- Include in handoff: `status: blocked`, `blockers: ["MCP {name} unavailable"]`
+- HALT - Do not attempt workarounds for critical MCPs
+
+**If optional MCP is unavailable:**
+- Note the limitation
+- Proceed with fallback approach
+- Document in handoff: `notes: "Built without {mcp} - manual review recommended"`
 ```
 
-3. Update `stats.total_agents_created`
+### ShadCN MCP Pattern
 
-### If Agent Doesn't Work (Later Feedback)
-If user reports issues later, record in `failed_patterns`:
-```yaml
-- name: agent-name
-  reason: Why it failed
-  lesson: What to do differently
+When implementing UI components with ShadCN MCP available:
+
+```markdown
+## ShadCN Component Implementation
+
+**ALWAYS call demo/docs first before implementing any ShadCN component:**
+
+1. Call the component demo tool to see usage:
+   - Review available variants, sizes, and props
+   - Note any required imports or dependencies
+
+2. Implement following the exact patterns shown:
+   - Use correct import paths
+   - Apply proper variant props
+   - Follow composition patterns for complex components
+
+3. Never guess component APIs—always verify first
+
+Example flow:
+- Need a Button? → Call shadcn demo for Button → See variants (default, destructive, outline, etc.) → Implement with correct props
 ```
 
-**Confirm completion with user.**
+### MagicPatterns MCP Pattern
+
+When user provides a MagicPatterns link:
+
+```markdown
+## MagicPatterns Link Handling
+
+**NEVER build from scratch when a MagicPatterns link is provided.**
+
+1. Extract the pattern/design ID from the link
+2. Use MagicPatterns MCP to fetch the generated code
+3. Adapt the fetched code for the project:
+   - Update imports to match project structure
+   - Apply project's styling conventions (Tailwind config, CSS variables)
+   - Integrate with project's state management if needed
+   - Ensure component follows project's file organization
+
+4. The MagicPatterns design represents user's intent—preserve the design, adapt the implementation
+```
+
+### Background vs Foreground Agent Warning
+
+**Critical limitation**: MCP tools are NOT available in background subagents.
+
+If your agent needs MCP access:
+- It must run in foreground mode
+- Background tasks that need MCPs will fail silently
+- Consider this when designing agent workflows
+
+---
 
 ## Quick Reference
 
@@ -317,6 +381,8 @@ See the dedicated template files for full examples and minimal templates:
 - **Non-Story**: `NON-STORY-AGENT-TEMPLATE.md`
 
 ### Available Tools Reference
+
+**Core Tools** (always available):
 | Tool | Purpose |
 |------|---------|
 | `Read` | Read file contents |
@@ -330,6 +396,16 @@ See the dedicated template files for full examples and minimal templates:
 | `Task` | Delegate to subagents |
 | `LSP` | Code intelligence |
 
+**MCP Tools** (available when configured):
+| MCP | Common Tools | Use Case |
+|-----|--------------|----------|
+| ShadCN | Component demos, installation | UI component implementation |
+| MagicPatterns | Get pattern code | Fetch designed components |
+| Context7 | Query docs | Up-to-date library documentation |
+| Playwright | Browser automation | E2E testing, screenshots |
+
+**Remember**: Omit `tools:` field to inherit all available tools including MCPs.
+
 ### Model Selection Guide
 | Model | Best For | Cost |
 |-------|----------|------|

package/skills/agent-creator/STORY-AGENT-TEMPLATE.md

@@ -10,7 +10,6 @@
 ---
 name: {agent-name}
 description: {Specialty} story executor. Requires story number or name.
-tools: Read, Glob, Grep, Bash, Edit, Write
 model: {sonnet|haiku|opus|inherit}
 ---
 
@@ -24,6 +23,24 @@ You are a {specialty} agent. Your role is to execute user stories with a focus o
 - Story number: e.g., "3.2", "story-3.2", "S3.2"
 - Story name: e.g., "user authentication flow"
 
+## First Action: MCP Availability Check
+
+Before invoking /dev-story, verify required tools are available:
+
+1. **Review story requirements** for MCP dependencies:
+   - UI components mentioned? → Need ShadCN MCP
+   - MagicPatterns link provided? → Need MagicPatterns MCP
+   - External API integration? → Context7 MCP helpful
+
+2. **If critical MCP is unavailable:**
+   - Output: `ESCALATE: Required MCP '{mcp-name}' not available. Please enable it and retry.`
+   - Set handoff: `status: blocked`, `blockers: ["MCP {name} unavailable"]`
+   - HALT immediately
+
+3. **If optional MCP is unavailable:**
+   - Note limitation and proceed
+   - Document in handoff notes
+
 ## Single Responsibility: Execute /dev-story
 
 **Your ONLY job is to invoke /dev-story with the provided story identifier.**
@@ -40,6 +57,21 @@ The /dev-story workflow handles ALL implementation work:
 - Validating against acceptance criteria
 - Updating the story file with completion status
 
+## MCP Usage Patterns
+
+### ShadCN Components
+When implementing UI components with ShadCN MCP:
+1. **ALWAYS call demo/docs first** before implementing any component
+2. Review available variants, sizes, and props
+3. Implement following the exact patterns shown
+4. Never guess component APIs—verify first
+
+### MagicPatterns Designs
+When a MagicPatterns link is provided:
+1. **NEVER build from scratch**—use the MCP to fetch the code
+2. Adapt fetched code for project structure
+3. Preserve the design intent, adapt the implementation
+
 ## TDD Requirements
 
 These practices are enforced by /dev-story. Include them so the workflow follows TDD:
@@ -59,8 +91,10 @@ This context is passed to /dev-story for implementation guidance.
 ## Constraints
 
 - MUST receive a valid story identifier before proceeding
+- MUST check MCP availability before starting work
 - MUST NOT implement anything directly - delegate to /dev-story
 - MUST NOT skip the /dev-story invocation
+- MUST escalate if critical MCP is unavailable
 
 ## If /dev-story Fails
 
@@ -106,7 +140,6 @@ After /dev-story completes, you MUST output this structured handoff:
 ---
 name: {name}
 description: {Specialty} story executor. Requires story number or name.
-tools: Read, Glob, Grep, Bash, Edit, Write
 model: sonnet
 ---
 
@@ -114,7 +147,13 @@ You are a {specialty} agent executing stories via /dev-story.
 
 **Required Input**: Story number (e.g., "3.2") or story name
 
-**On Launch**: Immediately execute `/dev-story {story-identifier}`
+**First Action**: Check MCP availability. If critical MCP missing → ESCALATE and HALT.
+
+**On Launch**: Execute `/dev-story {story-identifier}`
+
+**MCP Patterns**:
+- ShadCN: Call demo first, then implement with correct props
+- MagicPatterns: Fetch code via MCP, adapt for project (never build from scratch)
 
 All implementation is handled by /dev-story. You provide {specialty} context.
 
@@ -131,7 +170,6 @@ All implementation is handled by /dev-story. You provide {specialty} context.
 ---
 name: frontend
 description: Frontend/React story executor. Requires story number or name.
-tools: Read, Glob, Grep, Bash, Edit, Write
 model: sonnet
 ---
 
@@ -141,13 +179,35 @@ You are a frontend specialist executing stories via /dev-story.
 
 **Required Input**: Story number (e.g., "3.2") or story name
 
-**On Launch**: Immediately execute `/dev-story {story-identifier}`
+## First Action: MCP Availability Check
+
+Before starting:
+1. Check if story involves UI components → verify ShadCN MCP available
+2. Check if MagicPatterns link provided → verify MagicPatterns MCP available
+3. If critical MCP missing: `ESCALATE: Required MCP '{name}' not available` → HALT
+
+**On Launch**: Execute `/dev-story {story-identifier}`
 
 All implementation is handled by /dev-story. Your frontend focus provides context for:
 - React component patterns
 - UI/UX considerations
 - CSS/styling approaches
 
+## MCP Usage Patterns
+
+### ShadCN Components
+1. **ALWAYS call demo first** before implementing any component
+2. Review variants, sizes, props from the demo output
+3. Implement with correct imports and props
+4. Never guess—verify component API first
+
+### MagicPatterns Designs
+When user provides a MagicPatterns link:
+1. **NEVER build from scratch**
+2. Use MCP to fetch the generated code
+3. Adapt for project: update imports, apply project styles
+4. Preserve design intent
+
 ## TDD Requirements
 
 - **Red-Green-Refactor**: Write failing test → make it pass → improve code
@@ -176,7 +236,7 @@ After /dev-story completes, output:
     tests_run: [count]
     tests_failed: [count]
     coverage: [percentage]
-    blockers: none | [list]
+    blockers: none | [list MCP unavailability here if relevant]
     next_action: proceed | escalate | retry
     error_summary: null | "[error if any]"
     === END HANDOFF ===
@@ -189,11 +249,17 @@ After /dev-story completes, output:
 Before saving a story-based agent, verify:
 
 1. **Name format**: `{lowercase-alphanumeric-hyphens}`
-2. **Tools list**: Only valid Claude Code tools
+2. **Tool access**:
+   - ✅ Best: No `tools:` field (inherits all including MCPs)
+   - ✅ OK: `disallowedTools:` for specific restrictions
+   - ❌ Avoid: Explicit `tools:` list (blocks MCP access)
 3. **Model**: `sonnet`, `haiku`, `opus`, or `inherit`
 4. **Description**: Includes "Requires story number or name"
 5. **Content includes**:
    - "Required Input" section for story identifier
+   - **MCP Availability Check** as first action
    - `/dev-story` invocation instruction
+   - **MCP Usage Patterns** (ShadCN demo-first, MagicPatterns fetch)
+   - Escalation behavior for missing critical MCPs
    - NO direct implementation steps (only delegation)
    - **Handoff Format section** with `=== AGENT HANDOFF ===` block (required for orchestrator workflows)

package/skills/agent-creator/REGISTRY.yaml

@@ -1,107 +0,0 @@
-# Agent Creator Registry
-# Tracks successfully created agents for reuse and learning
-
-# Last updated by skill
-last_updated: 2026-01-12
-
-# Successfully created agents that can be reused
-# Format:
-#   - name: agent-name (without tmp- prefix)
-#     purpose: what task/specialization it handles
-#     tools: [list of tools]
-#     model: model used
-#     created: date
-#     project_context: what project/task it was created for
-#     success_notes: what worked well
-#     template_file: path to the template if saved
-#     reuse_count: how many times this pattern was reused
-
-successful_agents:
-  - name: upgrade-specialist
-    purpose: Framework/SDK upgrades (Next.js, React, TypeScript, Supabase)
-    tools: [Read, Glob, Grep, Bash, Edit, Write]
-    model: sonnet
-    created: 2026-01-12
-    project_context: VT SaaS Template - Epic 1 Foundation Modernization (Stories 1.1-1.4)
-    success_notes: Story-based agent with upgrade best practices, breaking change handling, validation checklist
-    template_file: null
-    reuse_count: 0
-
-  - name: refactor-specialist
-    purpose: Code refactoring and rebranding (search/replace, naming consistency)
-    tools: [Read, Glob, Grep, Bash, Edit, Write]
-    model: sonnet
-    created: 2026-01-12
-    project_context: VT SaaS Template - Epic 1 Foundation Modernization (Story 1.5)
-    success_notes: Story-based agent with grep strategies, i18n awareness, metadata updates
-    template_file: null
-    reuse_count: 0
-
-  - name: error-handling-specialist
-    purpose: Error boundaries, API error standardization, graceful failure patterns
-    tools: [Read, Glob, Grep, Bash, Edit, Write]
-    model: sonnet
-    created: 2026-01-12
-    project_context: VT SaaS Template - Epic 1 Foundation Modernization (Stories 1.6-1.7)
-    success_notes: Story-based agent with error boundary hierarchy, HTTP status code patterns, user-friendly messaging
-    template_file: null
-    reuse_count: 0
-
-  - name: qa-validator
-    purpose: CI/CD validation, feature testing, post-upgrade verification, performance audits
-    tools: [Read, Glob, Grep, Bash, Edit, Write]
-    model: sonnet
-    created: 2026-01-12
-    project_context: VT SaaS Template - Epic 1 Foundation Modernization (Stories 1.8-1.9)
-    success_notes: Story-based agent with CI/CD checks, manual testing checklists, Lighthouse audit guidance
-    template_file: null
-    reuse_count: 0
-
-# Example entry:
-# successful_agents:
-#   - name: api-integrator
-#     purpose: External API integration with error handling
-#     tools: [Read, Write, WebFetch, Bash]
-#     model: sonnet
-#     created: 2025-01-15
-#     project_context: HealthCompanion - Dify API integration
-#     success_notes: Good at handling SSE streams, rate limiting
-#     template_file: .claude/skills/agent-creator/templates/api-integrator.md
-#     reuse_count: 0
-
-# Agent patterns that didn't work well (learn from failures)
-failed_patterns: []
-
-# Example:
-# failed_patterns:
-#   - name: mega-agent
-#     reason: Too many responsibilities, confused context
-#     lesson: Keep agents single-purpose
-
-# Preferred combinations for common tasks
-recommended_combinations:
-  feature_development:
-    description: Full feature implementation workflow
-    agents: [explorer, implementer, tester, reviewer]
-
-  bug_fix:
-    description: Debug and fix issues
-    agents: [debugger, tester]
-
-  refactor:
-    description: Code restructuring
-    agents: [explorer, refactorer, tester]
-
-  api_integration:
-    description: External service integration
-    agents: [api-integrator, tester]
-
-  documentation:
-    description: Documentation updates
-    agents: [explorer, documenter]
-
-# Statistics
-stats:
-  total_agents_created: 4
-  total_reuses: 0
-  most_reused_agent: null