@torka/claude-workflows 0.6.3 → 0.7.1

package/commands/git-local-cleanup-push-pr.md

@@ -37,8 +37,12 @@ Before any operations, verify the environment is safe:
 
 8. **Build worktree inventory**: Run `git worktree list --porcelain` to detect all worktrees.
    - Parse the output to build a map: `{ branch_name -> worktree_path }`
-   - **For each worktree path, verify it exists on the filesystem**
-   - **If a path doesn't exist (stale entry), run `git worktree prune` to clean it up before continuing**
+   - **For each worktree path:**
+     a) Verify the directory exists on the filesystem
+     b) If it exists, verify git metadata is valid: `git -C <path> rev-parse --git-dir 2>/dev/null`
+     c) If directory exists but git command fails, this is a **stale worktree** (metadata broken but directory remains)
+   - **If any paths don't exist OR have invalid git metadata, run `git worktree prune` to clean up before continuing**
+   - After pruning, re-run `git worktree list --porcelain` to get the updated inventory
    - Identify which worktree is the main worktree vs linked worktrees
    - For each branch, record if it's checked out in a worktree and where
 
@@ -132,6 +136,8 @@ Store the WIP branches list for use in subsequent phases. Also maintain a separa
 
 ## Phase 3: Cleanup Merged Branches
 
+**Note on GitHub auto-delete:** Many repositories have "Automatically delete head branches" enabled in GitHub settings. When enabled, merged/squash-merged PR branches are automatically deleted from the remote. The workflow handles this gracefully - if remote deletion fails because the branch is already gone, it continues normally.
+
 For all branches identified as merged (via regular merge OR squash merge):
 
 ### Step 1: Categorize merged branches by worktree status
@@ -190,8 +196,14 @@ Options:
    - WARN: "Worktree at '<path>' has uncommitted changes that will be LOST"
    - Ask for explicit confirmation: "Proceed anyway?" / "Skip this worktree"
    - If skip, move to next branch
-3. Remove worktree: `git worktree remove <worktree-path>`
-4. If removal fails (locked, etc.), inform user and skip
+3. Remove worktree: `git worktree remove --force <worktree-path>`
+   - The `--force` flag is needed because worktrees often contain untracked build artifacts (.next, node_modules, coverage, etc.)
+   - This is safe here because we already: (a) confirmed the branch is merged/squash-merged, (b) warned about uncommitted changes if any
+4. If removal still fails (locked, etc.):
+   a) Run `git worktree prune` to clean up stale metadata
+   b) If directory still exists, inform user: "Leftover directory at '<path>' needs manual removal: `rm -rf '<path>'`"
+   c) **Do NOT attempt `rm -rf` directly** - this may be blocked by safety hooks in some environments
+   d) Continue with branch deletion if possible
 5. Proceed to delete branch (now safe)
 
 **If option 2 (Skip):**
@@ -207,7 +219,10 @@ Options:
 
 For each branch now eligible for deletion:
 - Delete local: `git branch -d <branch>` (use `-D` for squash-merged branches that git doesn't recognize as merged)
-- Delete remote (if exists): `git push <remote> --delete <branch>`
+- Delete remote (if tracking branch exists):
+  1. First check if remote branch exists: `git ls-remote --heads <remote> <branch>`
+  2. If output is empty, remote branch is already deleted (likely by GitHub auto-delete) - skip remote deletion
+  3. If remote branch exists: `git push <remote> --delete <branch>`
 
 ### Step 6: Clean up orphaned tracking branches
 
@@ -407,7 +422,7 @@ If the workflow fails at any point, display:
 
 ### Worktree Safety Rules
 - NEVER remove a worktree with uncommitted changes without explicit user confirmation
-- NEVER force remove a worktree (`git worktree remove --force`) - always handle uncommitted changes properly
+- `--force` flag for worktree removal IS allowed when: (a) branch is confirmed merged/squash-merged, AND (b) uncommitted changes have been checked and user warned if any exist. The `--force` is needed to handle untracked build artifacts (.next, node_modules, etc.)
 - ALWAYS check worktree status (`git -C <path> status --porcelain`) before attempting branch deletion
 - ALWAYS run `git worktree prune` after removing worktrees to clean up stale entries
 - NEVER attempt to remove the main worktree (git will error, but check anyway)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torka/claude-workflows",
-  "version": "0.6.3",
+  "version": "0.7.1",
   "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)