@torka/claude-workflows 0.7.1 → 0.9.0

package/skills/agent-creator/SKILL.md

@@ -12,12 +12,27 @@ Create custom Claude Code sub-agents tailored to your project's needs. All agent
 
 **All created agents are story-focused by default.** This means:
 1. Every agent accepts a **story identifier** as input (story number or name)
-2. Every agent **must invoke `/dev-story`** as their first action when launched
+2. Every agent uses **smart routing** to auto-detect story type and invoke the correct workflow
 3. The story context drives all agent work
 
+### Smart Workflow Routing
+
+Agents analyze story tasks and automatically route to the appropriate workflow:
+
+| Story Contains | Routes To |
+|----------------|-----------|
+| Only UI keywords | `/dev-story-ui` |
+| Only Backend keywords | `/dev-story-backend` |
+| Both or unclear | `/dev-story-fullstack` |
+
+**Detection Keywords:**
+- **UI**: component, page, layout, visual, form, button, modal, card, dialog, toast, responsive, CSS, Tailwind, shadcn, MagicPatterns, screenshot
+- **Backend**: API, endpoint, database, service, migration, auth, middleware, validation, schema, query, route handler, Drizzle, ORM
+
 ### Why Story-Based?
 - Ensures traceability from story → implementation
 - Provides clear scope boundaries for the agent
+- Smart routing picks the right workflow automatically
 - Maintains sprint tracking via `sprint-status.yaml`
 - Aligns with BMAD Method workflows
 
@@ -88,20 +103,17 @@ Present findings to user:
 
 Based on context, design the agent architecture:
 
-### Common Agent Patterns (All Story-Based)
+### Story Agent Pattern (Default)
 
-All agents below accept a story identifier and invoke `/dev-story`. The specialty provides context.
+All story agents use the **universal template** with smart routing:
 
-| 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 |
+| Agent Examples | Specialty Focus |
+|----------------|-----------------|
+| `frontend`, `react-dev`, `ui-specialist` | Frontend/React expertise |
+| `api-dev`, `db-specialist`, `auth-dev` | Backend/API expertise |
+| `feature-dev`, `saas-dev`, `nextjs-fullstack` | Full-stack expertise |
 
-**Note**: Agents inherit all available tools by default (including MCPs). Only use `disallowedTools` when explicit restrictions are needed.
+**Note**: Agents inherit all available tools by default (including MCPs). The agent auto-detects story type and routes to the correct workflow.
 
 ### Non-Story Agent Patterns (Rare - Only When Explicitly Requested)
 
@@ -111,26 +123,49 @@ All agents below accept a story identifier and invoke `/dev-story`. The specialt
 | `documenter` | Documentation-only updates | None (inherits all) |
 
 ### Design Considerations
-- **Story-first**: Default to story-based agents that invoke `/dev-story`
+- **Universal template**: All story agents use the same template with smart routing
+- **Persona-focused**: Agent creation is about defining expertise and approach
+- **Auto-routing**: Story type detection happens at execution time, not creation time
 - **Single responsibility**: Each agent has one specialty focus
-- **Minimal wrapper**: Agents delegate to `/dev-story` for all implementation
+- **Minimal wrapper**: Agents are persona + handoff only; workflows handle all logic
 - **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
+- **No MCP checks in agents**: Workflows handle MCP availability checks
 
 ### CHECKPOINT 2
 Present agent design to user:
 - List of proposed agents with names and descriptions
-- Each agent's specialty and tool access
+- Each agent's specialty/persona focus
 - How agents will collaborate (if applicable)
 
 **Wait for user approval before proceeding.**
 
 ## Step 3: Community Research
 
-**IMPORTANT: Reference the detailed guide at `.claude/skills/agent-creator/COMMUNITY-REPOS.md`**
+### Action 1: Check Pre-Built Expertise Profiles (Do This First)
+
+**Read the profile index at `.claude/skills/agent-creator/expertise/INDEX.md`**
+
+Most agents fit one of these pre-built profiles:
+
+| Profile | Use For |
+|---------|---------|
+| `react-frontend.md` | UI components, forms, modals, accessibility |
+| `backend-api.md` | API routes, auth, validation, error handling |
+| `nextjs-fullstack.md` | Pages, layouts, Server Components, App Router |
+| `testing.md` | Unit tests, E2E tests, coverage, fixtures |
+| `database-orm.md` | Schema, migrations, Drizzle queries |
+| `devops-ci.md` | CI/CD, deployment, secrets, GitHub Actions |
+
+**If a profile matches 80%+**: Extract keywords, competencies, and anti-patterns. Skip repo research.
+
+**If no good match**: Proceed to Action 2.
 
-### Research Limits (Mandatory)
+### Action 2: Repo Research (Only If Needed)
+
+**Reference the detailed guide at `.claude/skills/agent-creator/COMMUNITY-REPOS.md`**
+
+#### Research Limits (Mandatory)
 
 | Activity | Maximum |
 |----------|---------|
@@ -139,7 +174,7 @@ Present agent design to user:
 | Web searches | 2 queries |
 | Total research time | 10 minutes |
 
-### Curated Repos (Check First)
+#### Curated Repos (Check First)
 
 | Repository | URL |
 |------------|-----|
@@ -151,7 +186,16 @@ Present agent design to user:
 | compound-engineering-plugin | https://github.com/EveryInc/compound-engineering-plugin |
 | claude-code-workflows | https://github.com/OneRedOak/claude-code-workflows |
 
-### Evaluation Criteria
+#### Research Questions
+
+When reviewing repos, answer these questions (see COMMUNITY-REPOS.md for details):
+1. What problem does this agent solve?
+2. What expertise does it encode?
+3. What patterns can be reused?
+4. What limitations does it have?
+5. How should it be adapted?
+
+#### Evaluation Criteria
 
 Before using patterns from a repo, verify:
 1. **Recent Activity**: Last commit < 30 days (ideal) or < 90 days (acceptable)
@@ -168,8 +212,9 @@ gh repo view {owner}/{repo} --json stargazerCount,pushedAt
 
 ### CHECKPOINT 3
 Share research findings:
-- Which repos were checked (max 5)
-- Relevant patterns found
+- Profile(s) used (if applicable)
+- Which repos were checked (max 5, if Action 2 was needed)
+- Key patterns/competencies extracted
 - Adaptations proposed for this project
 
 **Wait for user approval before proceeding.**
@@ -180,11 +225,16 @@ Create agent files following Claude Code's native format.
 
 ### Templates
 
-**Use the template files for full specifications:**
-- **Story-Based (Default)**: `.claude/skills/agent-creator/STORY-AGENT-TEMPLATE.md`
-- **Non-Story (Rare)**: `.claude/skills/agent-creator/NON-STORY-AGENT-TEMPLATE.md`
+**Use the universal template for all story agents:**
+
+| Agent Type | Template File |
+|------------|---------------|
+| **Story Agents** (default) | `.claude/skills/agent-creator/STORY-AGENT-TEMPLATE.md` |
+| **Non-Story** (rare) | `.claude/skills/agent-creator/NON-STORY-AGENT-TEMPLATE.md` |
 
-Read the appropriate template file before creating agents.
+The universal template includes smart routing logic - agents auto-detect story type and route to the correct workflow (`/dev-story-ui`, `/dev-story-backend`, or `/dev-story-fullstack`).
+
+Read the template file before creating agents.
 
 ### File Naming Convention
 - Location: `.claude/agents/vt-bmad-dev-agents/{name}.md`
@@ -213,15 +263,13 @@ Before presenting to user, validate each agent:
 6. **Story-based validation** (for story agents):
    - Description mentions story input requirement
    - 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
+   - Content includes Execution section with routing logic (auto-detects story type)
+   - Content includes reference to all three workflows (`/dev-story-ui`, `/dev-story-backend`, `/dev-story-fullstack`)
+   - Content does NOT include:
+     - MCP availability checks (workflow handles this)
+     - Implementation steps (workflow handles this)
+     - Checklists (workflow handles this)
+   - Content includes Handoff Format section with `workflow_used` field
 
 ### CHECKPOINT 4
 For each agent, show:
@@ -293,73 +341,17 @@ disallowedTools: Bash
 
 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
+### MCP Checks Handled by Workflows (Not Agents)
 
-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
+**Important**: Agents no longer include MCP availability checks. The specialized workflows handle all MCP logic:
 
-**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
+| Workflow | MCP Handling |
+|----------|--------------|
+| `/dev-story-ui` | Probes shadcn, Playwright (required); Context7, MagicPatterns (optional) |
+| `/dev-story-backend` | Probes Context7, Serena (all optional with fallbacks) |
+| `/dev-story-fullstack` | Combines both based on task types |
 
-**If optional MCP is unavailable:**
-- Note the limitation
-- Proceed with fallback approach
-- Document in handoff: `notes: "Built without {mcp} - manual review recommended"`
-```
-
-### ShadCN MCP Pattern
-
-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
-```
-
-### 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
-```
+If a critical MCP is unavailable, the **workflow** will escalate and halt. Agents are minimal wrappers that only provide persona context and invoke the workflow.
 
 ### Background vs Foreground Agent Warning
 
@@ -376,9 +368,9 @@ If your agent needs MCP access:
 
 ### Templates
 
-See the dedicated template files for full examples and minimal templates:
-- **Story-Based**: `STORY-AGENT-TEMPLATE.md`
-- **Non-Story**: `NON-STORY-AGENT-TEMPLATE.md`
+See the template files for full examples and minimal templates:
+- **Story Agents** (default): `STORY-AGENT-TEMPLATE.md` - Universal template with smart routing
+- **Non-Story Agents** (rare): `NON-STORY-AGENT-TEMPLATE.md`
 
 ### Available Tools Reference