@torka/claude-workflows 0.1.0

package/skills/agent-creator/REGISTRY.yaml

@@ -0,0 +1,107 @@
+# 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

package/skills/agent-creator/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: vt-bmad-dev-agents-creator
+description: Creates custom Claude Code sub-agents for project tasks. Use when the user wants to create specialized agents, design agent workflows, or needs help breaking down complex tasks into agent-based solutions. All created agents are stored in .claude/agents/vt-bmad-dev-agents/.
+tools: Read, Write, Edit, Glob, Grep, Bash, WebFetch, WebSearch, Task, LSP
+---
+
+# Agent Creator Skill
+
+Create custom Claude Code sub-agents tailored to your project's needs. All agents are stored in `.claude/agents/vt-bmad-dev-agents/`.
+
+## Story-Based Agents (Default Behavior)
+
+**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
+3. The story context drives all agent work
+
+### Why Story-Based?
+- Ensures traceability from story → implementation
+- Provides clear scope boundaries for the agent
+- Maintains sprint tracking via `sprint-status.yaml`
+- Aligns with BMAD Method workflows
+
+## Workflow Overview
+
+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
+
+---
+
+## 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
+
+### Consider Built-in Agents First
+Before creating custom agents, check if built-ins suffice:
+- **Explore** - Codebase research
+- **general-purpose** - Multi-step tasks
+- **Plan** - Implementation planning
+
+Only create custom agents when you need project-specific knowledge or custom workflows.
+
+---
+
+## Step 1: Context Assessment
+
+Before creating agents, gather comprehensive context:
+
+### Project Analysis
+```bash
+# Understand project structure (use ls if tree not available)
+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
+ls -la .claude/skills/agent-creator/templates/ 2>/dev/null || echo "No templates yet"
+```
+
+Also read these files for context:
+- `CLAUDE.md` - Project instructions
+- `README.md` - Project overview
+- `package.json` - Dependencies and scripts (if exists)
+
+### Task Analysis Questions
+Ask the user:
+- What is the main task or goal you want to accomplish?
+- Are there specific technologies or frameworks involved?
+- What is the expected complexity (simple fix, feature, refactor, new project)?
+- Do you have preferences for how work should be divided?
+
+### CHECKPOINT 1
+Present findings to user:
+- Project type and tech stack identified
+- Task scope and complexity assessed
+- Proposed number of agents needed
+
+**Wait for user approval before proceeding.**
+
+## Step 2: Agent Design
+
+Based on context, design the agent architecture:
+
+### Common Agent Patterns (All Story-Based)
+
+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 |
+
+### 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 |
+
+### 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)
+
+### CHECKPOINT 2
+Present agent design to user:
+- List of proposed agents with names and descriptions
+- Each agent's specialty and tool access
+- 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`**
+
+### Research Limits (Mandatory)
+
+| Activity | Maximum |
+|----------|---------|
+| GitHub repo searches | 3 queries |
+| Repos to evaluate in detail | 5 repos |
+| Web searches | 2 queries |
+| Total research time | 10 minutes |
+
+### Curated Repos (Check First)
+
+| Repository | URL |
+|------------|-----|
+| claude-code-templates | https://github.com/davila7/claude-code-templates |
+| wshobson/agents | https://github.com/wshobson/agents |
+| claude-flow | https://github.com/ruvnet/claude-flow |
+| awesome-claude-code | https://github.com/hesreallyhim/awesome-claude-code |
+| SuperClaude Framework | https://github.com/SuperClaude-Org/SuperClaude_Framework |
+| compound-engineering-plugin | https://github.com/EveryInc/compound-engineering-plugin |
+| claude-code-workflows | https://github.com/OneRedOak/claude-code-workflows |
+
+### Evaluation Criteria
+
+Before using patterns from a repo, verify:
+1. **Recent Activity**: Last commit < 30 days (ideal) or < 90 days (acceptable)
+2. **Stars**: 50+ preferred, 10+ minimum
+3. **Relevance**: Directly applicable to the task
+
+```bash
+# Quick repo check (if gh CLI available)
+gh repo view {owner}/{repo} --json stargazerCount,pushedAt
+
+# Fallback if gh CLI not available - use WebFetch
+# WebFetch("https://api.github.com/repos/{owner}/{repo}")
+```
+
+### CHECKPOINT 3
+Share research findings:
+- Which repos were checked (max 5)
+- Relevant patterns found
+- Adaptations proposed for this project
+
+**Wait for user approval before proceeding.**
+
+## Step 4: Agent Creation
+
+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`
+
+Read the appropriate template file before creating agents.
+
+### File Naming Convention
+- Location: `.claude/agents/vt-bmad-dev-agents/{name}.md`
+- Naming: lowercase, hyphens only
+- Examples: `frontend.md`, `api-integrator.md`
+
+### Pre-Save Validation
+Before presenting to user, validate each agent:
+
+1. **Name format**: Must be `{lowercase-alphanumeric-hyphens}`
+   - 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
+
+3. **Model**: Must be one of: `sonnet`, `haiku`, `opus`, `inherit`
+
+4. **Description**: Should be 20-300 characters, specific enough to trigger correctly
+   - **Story agents MUST include**: "Requires story number or name"
+
+5. **No duplicates**: Check `.claude/agents/vt-bmad-dev-agents/` for existing agent with same name
+
+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)
+
+### CHECKPOINT 4
+For each agent, show:
+- Complete agent file content
+- File path where it will be saved
+- Validation status (all checks passed)
+
+**Wait for user approval of each agent before saving.**
+
+## Step 5: Validation & Deployment
+
+### Save Agent Files
+```bash
+# Ensure agents directory exists
+mkdir -p .claude/agents/vt-bmad-dev-agents
+
+# Write each approved agent file
+# (Done via Write tool after user approval)
+```
+
+### Verify Installation
+```bash
+# List created agents
+ls -la .claude/agents/vt-bmad-dev-agents/
+
+# Show agent count
+echo "Created $(ls .claude/agents/vt-bmad-dev-agents/*.md 2>/dev/null | wc -l) agents"
+```
+
+### Usage Instructions
+After creation, agents work in two ways:
+- **Automatic**: When your task matches the agent's description, Claude may use it automatically
+- **Explicit**: Reference the agent by name in your prompt, e.g., "Use the tester agent to..."
+
+### Cleanup Instructions
+When agents are no longer needed:
+```bash
+# Remove all agents in the directory
+rm -rf .claude/agents/vt-bmad-dev-agents/
+
+# Or remove specific agent
+rm .claude/agents/vt-bmad-dev-agents/{name}.md
+```
+
+### CHECKPOINT 5 (Final)
+Present summary:
+- All agents created successfully
+- 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?"
+
+### If User Wants to Save Pattern
+Update `.claude/skills/agent-creator/REGISTRY.yaml`:
+
+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
+```
+
+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
+```
+
+3. Update `stats.total_agents_created`
+
+### 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
+```
+
+**Confirm completion with user.**
+
+## Quick Reference
+
+### 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`
+
+### Available Tools Reference
+| Tool | Purpose |
+|------|---------|
+| `Read` | Read file contents |
+| `Write` | Create new files |
+| `Edit` | Modify existing files |
+| `Glob` | Find files by pattern |
+| `Grep` | Search file contents |
+| `Bash` | Run shell commands |
+| `WebFetch` | Fetch web content |
+| `WebSearch` | Search the web |
+| `Task` | Delegate to subagents |
+| `LSP` | Code intelligence |
+
+### Model Selection Guide
+| Model | Best For | Cost |
+|-------|----------|------|
+| `haiku` | Simple, fast tasks | Lowest |
+| `sonnet` | Balanced reasoning | Medium |
+| `opus` | Complex reasoning | Highest |
+| `inherit` | Match parent model | Varies |

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

@@ -0,0 +1,199 @@
+# Story-Based Agent Template (Default)
+
+**All agents are story-execution wrappers by default.** They accept a story identifier and delegate to `/dev-story`.
+
+---
+
+## Full Template
+
+```markdown
+---
+name: {agent-name}
+description: {Specialty} story executor. Requires story number or name.
+tools: Read, Glob, Grep, Bash, Edit, Write
+model: {sonnet|haiku|opus|inherit}
+---
+
+# {Agent Name} - Story Executor
+
+You are a {specialty} agent. Your role is to execute user stories with a focus on {specialty area}.
+
+## Required Input
+
+**Story Identifier** (MANDATORY): Accepts either:
+- Story number: e.g., "3.2", "story-3.2", "S3.2"
+- Story name: e.g., "user authentication flow"
+
+## Single Responsibility: Execute /dev-story
+
+**Your ONLY job is to invoke /dev-story with the provided story identifier.**
+
+Upon receiving a story identifier, immediately execute:
+```
+/dev-story {story-identifier}
+```
+
+The /dev-story workflow handles ALL implementation work:
+- Loading and validating the story file
+- Updating sprint status
+- Implementing tasks and subtasks
+- Validating against acceptance criteria
+- Updating the story file with completion status
+
+## TDD Requirements
+
+These practices are enforced by /dev-story. Include them so the workflow follows TDD:
+- **Red-Green-Refactor**: Write failing test → make it pass → improve code while keeping tests green
+- **Task-driven**: Never implement anything not mapped to a specific task/subtask in the story file
+- **Test coverage**: Every task/subtask must have comprehensive unit tests before marking complete
+- **All tests green**: All existing tests must pass 100% before story is ready for review
+
+## Specialty Context
+
+While /dev-story handles execution, your {specialty} focus means:
+- {Specialty consideration 1}
+- {Specialty consideration 2}
+
+This context is passed to /dev-story for implementation guidance.
+
+## Constraints
+
+- MUST receive a valid story identifier before proceeding
+- MUST NOT implement anything directly - delegate to /dev-story
+- MUST NOT skip the /dev-story invocation
+
+## If /dev-story Fails
+
+If the story cannot be found or /dev-story fails:
+1. Ask user to clarify the story identifier
+2. Do NOT attempt implementation without a valid story
+
+## Handoff Format (Required for Orchestrator)
+
+After /dev-story completes, you MUST output this structured handoff:
+
+    === AGENT HANDOFF ===
+    agent: {agent-name}
+    story: [story number, e.g., "2.3"]
+    status: completed | failed | blocked
+    files_changed:
+      - [list all modified/created files]
+    tests_passed: true | false
+    tests_run: [count]
+    tests_failed: [count]
+    coverage: [percentage or "unknown"]
+    blockers: none | [list any blockers]
+    next_action: proceed | escalate | retry
+    error_summary: null | "[failure description if any]"
+    === END HANDOFF ===
+
+**Status Definitions:**
+- `completed`: All tasks done, tests pass, ready for quality gate
+- `failed`: Errors encountered that could not be resolved
+- `blocked`: External dependency prevents completion
+
+**Next Action:**
+- `proceed`: Move to quality gate verification
+- `retry`: Attempt to fix issues and re-run
+- `escalate`: Requires human intervention
+```
+
+---
+
+## Minimal Template
+
+```markdown
+---
+name: {name}
+description: {Specialty} story executor. Requires story number or name.
+tools: Read, Glob, Grep, Bash, Edit, Write
+model: sonnet
+---
+
+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}`
+
+All implementation is handled by /dev-story. You provide {specialty} context.
+
+**TDD**: Red-green-refactor. Tests before code. All tests must pass.
+
+**Handoff**: After /dev-story, output `=== AGENT HANDOFF ===` block with: agent, story, status, files_changed, tests_passed, tests_run, tests_failed, coverage, blockers, next_action, error_summary.
+```
+
+---
+
+## Complete Example: Frontend Agent
+
+```markdown
+---
+name: frontend
+description: Frontend/React story executor. Requires story number or name.
+tools: Read, Glob, Grep, Bash, Edit, Write
+model: sonnet
+---
+
+# Frontend Story Executor
+
+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}`
+
+All implementation is handled by /dev-story. Your frontend focus provides context for:
+- React component patterns
+- UI/UX considerations
+- CSS/styling approaches
+
+## TDD Requirements
+
+- **Red-Green-Refactor**: Write failing test → make it pass → improve code
+- **Task-driven**: Only implement what's in the story file
+- **Test coverage**: Every task/subtask needs unit tests before complete
+- **All tests green**: 100% pass before story is ready for review
+
+Use Bash for `npm run dev`, `npm test`, etc.
+
+## If /dev-story Fails
+
+1. Ask user to clarify the story identifier
+2. Do NOT attempt implementation without a valid story
+
+## Handoff Format (Required for Orchestrator)
+
+After /dev-story completes, output:
+
+    === AGENT HANDOFF ===
+    agent: frontend
+    story: [story number]
+    status: completed | failed | blocked
+    files_changed:
+      - [list files]
+    tests_passed: true | false
+    tests_run: [count]
+    tests_failed: [count]
+    coverage: [percentage]
+    blockers: none | [list]
+    next_action: proceed | escalate | retry
+    error_summary: null | "[error if any]"
+    === END HANDOFF ===
+```
+
+---
+
+## Validation Checklist
+
+Before saving a story-based agent, verify:
+
+1. **Name format**: `{lowercase-alphanumeric-hyphens}`
+2. **Tools list**: Only valid Claude Code tools
+3. **Model**: `sonnet`, `haiku`, `opus`, or `inherit`
+4. **Description**: Includes "Requires story number or name"
+5. **Content includes**:
+   - "Required Input" section for story identifier
+   - `/dev-story` invocation instruction
+   - NO direct implementation steps (only delegation)
+   - **Handoff Format section** with `=== AGENT HANDOFF ===` block (required for orchestrator workflows)