name	workflow-generator
description	Generate project-specific workflow commands (research, plan, implement, qa) by asking questions about the project and creating customized commands
allowed-tools	Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, TodoWrite

Workflow Generator Skill

This skill generates a complete set of project-specific workflow commands by asking questions about your project and creating customized /research, /plan, /implement, and /qa commands.

Purpose

Create a standardized workflow system adapted to any project's:

Tech stack and language
Build/test commands
Documentation structure
Quality gates and validation criteria
Planning methodology

Template System

Template Path Resolution

Templates are stored in plugins/meta/skills/workflow-generator/templates/. When this skill uses the Read tool:

During marketplace development: Paths are relative to repository root
When plugin is installed: Claude Code resolves paths relative to plugin installation location
Template paths in this skill use the format: plugins/meta/skills/workflow-generator/templates/<template-name>.md

Template Syntax

Templates use two types of variable substitution:

1. Simple Variable Substitution Replace {{VARIABLE}} with actual values:

{{PROJECT_TYPE}} → "Phoenix Application"
{{DOCS_LOCATION}} → ".thoughts"
{{TEST_COMMAND}} → "mix test"

2. Handlebars Conditionals (in some templates) Templates may use Handlebars syntax for conditional content:

{{#if PLANNING_STYLE equals "Detailed phases"}}
  Phase-based content
{{/if}}

{{#if PLANNING_STYLE equals "Task checklist"}}
  Checklist-based content
{{/if}}

How to handle Handlebars syntax:

Handlebars conditionals are preserved in generated commands (not substituted)
The generated command will contain the conditional logic
Claude will evaluate conditionals when the command is executed
This allows generated commands to adapt behavior based on context

Execution Flow

When invoked, this skill will:

Discover Project Context
Ask Customization Questions
Generate Workflow Commands
Create Supporting Documentation
Provide Usage Instructions

Step 1: Discover Project Context

1.1 Detect Project Type

Analyze the current directory to understand the project:

# Check for common project markers
ls package.json 2>/dev/null && echo "nodejs"
ls mix.exs 2>/dev/null && echo "elixir"
ls Cargo.toml 2>/dev/null && echo "rust"
ls go.mod 2>/dev/null && echo "go"
ls setup.py pyproject.toml 2>/dev/null && echo "python"
ls pom.xml build.gradle 2>/dev/null && echo "java"

1.2 Check Existing Structure

# Check for existing .claude directory
ls .claude/commands/*.md 2>/dev/null | wc -l
ls .claude/agents/*.md 2>/dev/null | wc -l

1.3 Detect Build Tools

Look for common build/test patterns:

Makefile with test target
package.json with scripts
mix.exs with test tasks
Cargo.toml
go.mod

Step 2: Ask Customization Questions

Use TodoWrite to track progress:

1. [in_progress] Discover project context
2. [pending] Ask customization questions
3. [pending] Generate /research command
4. [pending] Generate /plan command
5. [pending] Generate /implement command
6. [pending] Generate /qa command
7. [pending] Generate /oneshot command
8. [pending] Generate /interview command
9. [pending] Create documentation
10. [pending] Present usage instructions

Mark step 1 completed, step 2 in progress.

Question 1: Elixir Project Type

Header: "Project Type" Question: "What type of Elixir project is this?" multiSelect: false Options:

Label: "Phoenix Application", Description: "Phoenix web application (full-stack, API, LiveView)"
Label: "Library/Package", Description: "Reusable Hex package or library"
Label: "CLI/Escript", Description: "Command-line application or escript"
Label: "Umbrella Project", Description: "Umbrella project with multiple apps"

Question 2: Test Strategy

Header: "Testing" Question: "How do you run tests?" multiSelect: false Options:

Label: "mix test", Description: "Standard Mix test command"
Label: "make test", Description: "Using Makefile with test target"
Label: "Custom script", Description: "Custom test script or command"

Question 3: Documentation Location

Header: "Docs Location" Question: "Where should workflow documents (research, plans) be saved?" multiSelect: false Options:

Label: ".thoughts/", Description: "Hidden .thoughts directory (default pattern)"
Label: "docs/", Description: "Standard docs directory"
Label: ".claude/thoughts/", Description: "Inside .claude directory"
Label: "thoughts/", Description: "Visible thoughts directory"

Question 4: Quality Tools

Header: "Quality Tools" Question: "Which Elixir quality tools do you use?" multiSelect: true Options:

Label: "Credo", Description: "Static code analysis with Credo"
Label: "Dialyzer", Description: "Type checking with Dialyzer"
Label: "Sobelow", Description: "Security scanning for Phoenix apps"
Label: "ExDoc", Description: "Documentation validation"
Label: "mix_audit", Description: "Dependency security audit"
Label: "Format check", Description: "Code formatting validation"

Question 5: Planning Style

Header: "Planning" Question: "How detailed should implementation plans be?" multiSelect: false Options:

Label: "Detailed phases", Description: "Break work into numbered phases with specific file changes"
Label: "Task checklist", Description: "Simple checklist of tasks to complete"
Label: "Milestone-based", Description: "Organize by milestones/deliverables"

Question 6: WORKFLOWS.md Location

Header: "Workflows Doc" Question: "Where should the WORKFLOWS.md documentation file be saved?" multiSelect: false Options:

Label: ".claude/WORKFLOWS.md", Description: "Inside .claude directory (recommended)"
Label: "WORKFLOWS.md", Description: "Project root directory"
Label: "docs/WORKFLOWS.md", Description: "Inside docs directory"
Label: "README-WORKFLOWS.md", Description: "Project root with README prefix"

Step 3: Generate /research Command

Mark step 3 as in_progress in TodoWrite.

Read the template:

Use Read tool to read plugins/meta/skills/workflow-generator/templates/research-template.md
This contains the full command structure with placeholders

Perform variable substitution:

Replace these variables in the template:

{{PROJECT_TYPE}} → Answer from Question 1 (e.g., "Phoenix Application")
{{DOCS_LOCATION}} → Answer from Question 3 (e.g., ".thoughts")
{{PROJECT_TYPE_TAGS}} → Tags based on project type:
- Phoenix Application → "phoenix, web, elixir"
- Library/Package → "library, hex, elixir"
- CLI/Escript → "cli, escript, elixir"
- Umbrella Project → "umbrella, multi-app, elixir"
{{PROJECT_TYPE_SPECIFIC}} → Project-specific component types for agent prompts:
- Phoenix Application → "Phoenix contexts, controllers, LiveViews, and schemas"
- Library/Package → "public API modules and functions"
- CLI/Escript → "CLI commands, Mix tasks, and escript entry points"
- Umbrella Project → "umbrella apps and shared modules"

Write customized command:

Use Write tool to create .claude/commands/research.md
Content is the template with all variables substituted

Mark step 3 completed in TodoWrite.

Step 4: Generate /plan Command

Mark step 4 as in_progress in TodoWrite.

Read the template:

Use Read tool to read plugins/meta/skills/workflow-generator/templates/plan-template.md
This contains the full command structure with placeholders

Perform variable substitution:

Replace these variables in the template:

{{PLANNING_STYLE}} → Answer from Question 5 (e.g., "Detailed phases")
{{DOCS_LOCATION}} → Answer from Question 3 (e.g., ".thoughts")
{{TEST_COMMAND}} → Answer from Question 2, map to actual command:
- "mix test" → "mix test"
- "make test" → "make test"
- "Custom script" → Ask user what command to use
{{PROJECT_TYPE}} → Answer from Question 1
{{PROJECT_TYPE_TAGS}} → Same tags as research command
{{QUALITY_TOOLS_CHECKS}} → Expand based on Question 4 answers:
- If "Credo" selected: Add "- [ ] mix credo --strict passes"
- If "Dialyzer" selected: Add "- [ ] mix dialyzer passes"
- If "Sobelow" selected: Add "- [ ] mix sobelow --exit Low passes"
- If "Format check" selected: Add "- [ ] mix format --check-formatted passes"
- If "ExDoc" selected: Add "- [ ] mix docs succeeds (no warnings)"
- If "mix_audit" selected: Add "- [ ] mix deps.audit passes"
{{QUALITY_TOOLS_EXAMPLES}} → Same expansion as checks but as examples

Write customized command:

Use Write tool to create .claude/commands/plan.md
Content is the template with all variables substituted

Mark step 4 completed in TodoWrite.

Step 5: Generate /implement Command

Mark step 5 as in_progress in TodoWrite.

Read the template:

Use Read tool to read plugins/meta/skills/workflow-generator/templates/implement-template.md
This contains the full command structure with placeholders

Perform variable substitution:

Replace these variables in the template:

{{DOCS_LOCATION}} → Answer from Question 3
{{TEST_COMMAND}} → Actual test command from Question 2

{{VERIFICATION_COMMANDS}} → Per-phase verification commands:

# Always include:
mix compile --warnings-as-errors
{{TEST_COMMAND}}
mix format --check-formatted

# Add if selected in Question 4:
mix credo --strict  # if Credo
mix dialyzer  # if Dialyzer

{{FULL_VERIFICATION_SUITE}} → All quality checks expanded:
- Always: compile, test, format
- Conditionally: Credo, Dialyzer, Sobelow, ExDoc, mix_audit (if selected)
{{QUALITY_TOOLS_SUMMARY}} → Summary line for each enabled tool
{{OPTIONAL_QUALITY_CHECKS}} → Per-phase optional checks if tools enabled

Write customized command:

Use Write tool to create .claude/commands/implement.md
Content is the template with all variables substituted

Mark step 5 completed in TodoWrite.

Step 6: Generate /qa Command

Mark step 6 as in_progress in TodoWrite.

Read the template:

Use Read tool to read plugins/meta/skills/workflow-generator/templates/qa-template.md
This contains the full command structure with placeholders

Perform variable substitution:

Replace these variables in the template:

{{PROJECT_TYPE}} → Answer from Question 1
{{TEST_COMMAND}} → Actual test command from Question 2
{{DOCS_LOCATION}} → Answer from Question 3
{{PROJECT_TYPE_TAGS}} → Same tags as research command

{{QUALITY_TOOL_COMMANDS}} → Expand quality tool commands based on Question 4:

# Add for each selected tool:
mix credo --strict  # if Credo
mix dialyzer  # if Dialyzer
mix sobelow --exit Low  # if Sobelow
mix format --check-formatted  # if Format check
mix docs  # if ExDoc
mix deps.audit  # if mix_audit

{{QUALITY_TOOLS_RESULTS_SUMMARY}} → Summary lines for report template
{{QUALITY_TOOLS_DETAILED_RESULTS}} → Detailed result sections for enabled tools
{{SUCCESS_CRITERIA_CHECKLIST}} → Checklist items for each enabled tool
{{PROJECT_TYPE_SPECIFIC_OBSERVATIONS}} → Phoenix/Ecto/OTP observations based on project type
{{QUALITY_TOOL_INTEGRATION_GUIDE}} → Integration guidance for enabled tools
{{QUALITY_TOOLS_SUMMARY_DISPLAY}} → Display format for enabled tools in final output

Write customized command:

Use Write tool to create .claude/commands/qa.md
Content is the template with all variables substituted

Mark step 6 completed in TodoWrite.

Step 7: Generate /oneshot Command

Mark step 7 as in_progress in TodoWrite.

Read the template:

Use Read tool to read plugins/meta/skills/workflow-generator/templates/oneshot-template.md
This contains the full command structure with placeholders

Perform variable substitution:

Replace these variables in the template:

{{FEATURE_DESCRIPTION}} → User's feature description (from $ARGUMENTS)
{{DOCS_LOCATION}} → Answer from Question 3
{{TEST_COMMAND}} → Actual test command from Question 2
{{PROJECT_TYPE}} → Answer from Question 1
{{QUALITY_TOOLS}} → Boolean check if any quality tools selected
{{QUALITY_TOOLS_SUMMARY}} → Comma-separated list of enabled tools
{{QUALITY_TOOLS_STATUS}} → Status summary for each tool
{{QUALITY_TOOLS_LIST}} → List format of enabled tools
{{QA_PASSED}} → Conditional variable for success/failure branching

Write customized command:

Use Write tool to create .claude/commands/oneshot.md
Content is the template with all variables substituted

Mark step 7 completed in TodoWrite.

Step 8: Generate /interview Command

Mark step 8 as in_progress in TodoWrite.

Read the template:

Use Read tool to read plugins/meta/skills/workflow-generator/templates/interview-template.md
This contains the full command structure with placeholders

Perform variable substitution:

Replace these variables in the template:

{{PROJECT_TYPE}} → Answer from Question 1 (e.g., "Phoenix Application")
{{DOCS_LOCATION}} → Answer from Question 3 (e.g., ".thoughts")

The interview command is designed to be project-agnostic with dynamic question generation, so it needs minimal customization compared to other commands.

Write customized command:

Use Write tool to create .claude/commands/interview.md
Content is the template with variables substituted

Mark step 8 completed in TodoWrite.

Step 9: Create Documentation

Mark step 9 as in_progress in TodoWrite.

9.1 Create Workflow README

Create WORKFLOWS.md file at the location specified in Question 6.

File Location (based on Question 6 answer):

".claude/WORKFLOWS.md" → .claude/WORKFLOWS.md
"WORKFLOWS.md" → WORKFLOWS.md
"docs/WORKFLOWS.md" → docs/WORKFLOWS.md
"README-WORKFLOWS.md" → README-WORKFLOWS.md

If the answer is "docs/WORKFLOWS.md", create the docs directory first:

mkdir -p docs

Content for the WORKFLOWS.md file:

# Elixir Project Workflows

This project uses a standardized workflow system for research, planning, implementation, and quality assurance.

## Generated for: {{PROJECT_TYPE}} (Elixir)

---

## Available Commands

### /research

Research the codebase to answer questions and document existing implementations.

**Usage**:
```bash
/research "How does authentication work?"
/research "What is the API structure?"

Output: Research documents saved to {{DOCS_LOCATION}}/research-YYYY-MM-DD-topic.md

/plan

Create detailed implementation plans with success criteria.

Usage:

/plan "Add user profile page"
/plan "Refactor database layer"

Output: Plans saved to {{DOCS_LOCATION}}/plans/YYYY-MM-DD-description.md

Plan Structure: {{PLANNING_STYLE}}

/implement

Execute implementation plans with automated verification.

Usage:

/implement "2025-01-23-user-profile"
/implement   # Will prompt for plan selection

Verification Commands:

Compile: mix compile --warnings-as-errors
Test: {{TEST_COMMAND}}
Format: mix format --check-formatted {{#each QUALITY_TOOLS}}
{{this}} {{/each}}

/qa

Validate implementation against success criteria and project quality standards.

Usage:

/qa                    # General health check
/qa "plan-name"        # Validate specific plan implementation

Quality Gates: {{#each VALIDATION_CRITERIA}}

{{this}} {{/each}}

Fix Workflow (automatic): When critical issues are detected, /qa offers to automatically generate and execute a fix plan.

Fix Workflow (Automatic)

When /qa detects critical issues, it automatically offers to generate a fix plan and execute it.

Automatic Fix Flow:

/qa → ❌ Critical issues detected
    ↓
"Generate fix plan?" → Yes
    ↓
/plan "Fix critical issues from QA report: ..."
    ↓
Fix plan created at {{DOCS_LOCATION}}/plans/plan-YYYY-MM-DD-fix-*.md
    ↓
"Execute fix plan?" → Yes
    ↓
/implement fix-plan-name
    ↓
/qa → Re-validation
    ↓
✅ Pass or iterate

Manual Fix Flow:

/qa → ❌ Critical issues detected → Decline auto-fix
    ↓
Review QA report manually
    ↓
Fix issues manually or create plan: /plan "Fix [specific issue]"
    ↓
/qa → Re-validation

Oneshot with Auto-Fix:

The /oneshot command automatically attempts fix workflows when QA fails:

/oneshot "Feature" → Research → Plan → Implement → QA
                                                     ↓
                                          ❌ Fails with critical issues
                                                     ↓
                                    "Auto-fix and re-validate?" → Yes
                                                     ↓
                        /plan "Fix..." → /implement fix → /qa
                                                     ↓
                                          ✅ Pass → Complete oneshot

Benefits of Fix Workflow:

✅ Reuses existing plan/implement infrastructure
✅ Fix plans documented like feature plans
✅ Handles complex multi-step fixes
✅ Full audit trail in {{DOCS_LOCATION}}/plans/
✅ Iterative: Can re-run /qa to generate new fix plans

Workflow Sequence

The recommended workflow for new features:

Research (/research) - Understand current implementation
Plan (/plan) - Create detailed implementation plan
Implement (/implement) - Execute plan with verification
QA (/qa) - Validate against success criteria

Customization

These commands were generated based on your project configuration. You can edit them directly:

.claude/commands/research.md
.claude/commands/plan.md
.claude/commands/implement.md
.claude/commands/qa.md
.claude/commands/oneshot.md

To regenerate: /meta:workflow-generator

Project Configuration

Project Type: {{PROJECT_TYPE}} Tech Stack: Elixir Test Command: {{TEST_COMMAND}} Documentation: {{DOCS_LOCATION}} Planning Style: {{PLANNING_STYLE}}

Quality Tools: {{#each QUALITY_TOOLS}}

{{this}} {{/each}}


**Variable Substitution** for WORKFLOWS.md:
- `{{PROJECT_TYPE}}` → Answer from Question 1
- `{{DOCS_LOCATION}}` → Answer from Question 3
- `{{TEST_COMMAND}}` → Actual test command from Question 2
- `{{PLANNING_STYLE}}` → Answer from Question 5
- `{{QUALITY_TOOLS}}` → List from Question 4
- `{{VALIDATION_CRITERIA}}` → Expanded from Question 4

Use Write tool to create the file at the location determined above.

### 9.2 Create Documentation Directory

```bash
mkdir -p {{DOCS_LOCATION}}/research
mkdir -p {{DOCS_LOCATION}}/plans
mkdir -p {{DOCS_LOCATION}}/interview

Mark step 9 completed in TodoWrite.

Step 10: Present Usage Instructions

Mark step 10 as in_progress in TodoWrite.

Present a comprehensive summary to the user:

✅ Workflow commands generated successfully!

## Created Commands

.claude/ ├── commands/ │ ├── interview.md # Interactive context gathering │ ├── research.md # Research and document codebase │ ├── plan.md # Create implementation plans │ ├── implement.md # Execute plans with verification │ ├── qa.md # Validate implementation quality │ └── oneshot.md # Complete workflow in one command {{WORKFLOWS_MD_LOCATION}} # Complete workflow documentation


**Note**: Show the actual file path where WORKFLOWS.md was created based on Question 6 answer.

## Documentation Structure

{{DOCS_LOCATION}}/ ├── interview/ # Interview context documents ├── research/ # Research documents └── plans/ # Implementation plans


---

## Configuration Summary

**Project**: {{PROJECT_TYPE}} (Elixir)

**Commands Configured**:
- Compile: `mix compile --warnings-as-errors`
- Test: `{{TEST_COMMAND}}`
- Format: `mix format --check-formatted`

**Quality Tools Enabled**:
{{#each QUALITY_TOOLS}}
- {{this}}
{{/each}}

**Planning Style**: {{PLANNING_STYLE}}

---

## Quick Start

### 1. Research the Codebase

```bash
/research "How does [feature] work?"

This will:

Spawn parallel research agents
Document findings with file:line references
Save to {{DOCS_LOCATION}}/research-YYYY-MM-DD-topic.md

2. Create an Implementation Plan

/plan "Add new feature X"

This will:

Gather context via research
Present design options
Create phased plan with success criteria
Save to {{DOCS_LOCATION}}/plans/YYYY-MM-DD-feature-x.md

3. Execute the Plan

/implement "2025-01-23-feature-x"

This will:

Read the plan
Execute phase by phase
Run verification after each phase (mix compile, {{TEST_COMMAND}})
Update checkmarks
Pause for confirmation

4. Validate Implementation

/qa "feature-x"

This will:

Run all quality gate checks
Generate validation report
Provide actionable feedback

Workflow Example

Scenario: Adding a new Phoenix context

# 1. Research existing patterns
/research "How are contexts structured in this Phoenix app?"

# 2. Create implementation plan
/plan "Add Accounts context with user management"

# 3. Execute the plan
/implement "2025-01-23-accounts-context"

# 4. Validate implementation
/qa "accounts-context"

Customization

All generated commands are fully editable. Customize them to match your exact workflow:

Add custom validation: Edit .claude/commands/qa.md
Change plan structure: Edit .claude/commands/plan.md
Add research sources: Edit .claude/commands/research.md
Modify checkpoints: Edit .claude/commands/implement.md

Re-generate Commands

To regenerate these commands with different settings:

/workflow-generator

This will ask questions again and regenerate all commands.

Documentation

Full workflow documentation: {{WORKFLOWS_MD_LOCATION}}

Note: Show the actual file path where WORKFLOWS.md was created.

Next Steps

✅ Try your first research: /research "project structure"
Read workflow docs: {{WORKFLOWS_MD_LOCATION}}
Customize commands as needed (edit .claude/commands/*.md)
Start your first planned feature!

Note: Replace {{WORKFLOWS_MD_LOCATION}} with the actual file path.

Need help? Each command has detailed instructions in its markdown file.


Mark step 10 completed in TodoWrite.

Mark all todos as completed and present final summary to user.

---

## Important Notes

### Generic Core Components

The generated commands maintain these universal patterns:
- TodoWrite for progress tracking
- Parallel agent spawning (finder, analyzer)
- YAML frontmatter with git metadata
- file:line reference format
- Documentation vs evaluation separation
- Success criteria framework (automated vs manual)

### Elixir-Specific Customizations

Commands are customized based on:
- Elixir project type (Phoenix, Library, CLI, Umbrella)
- Test commands (mix test, make test, custom)
- Documentation location preferences
- Quality tools enabled (Credo, Dialyzer, Sobelow, etc.)
- Planning methodology

### Extensibility

All generated commands are templates that users can:
- Edit directly to add project-specific logic
- Extend with additional validation
- Modify to match team conventions
- Enhance with custom agent types

### Agent Types Referenced

Generated commands use these standard agents:
- `finder`: Locate files and patterns
- `analyzer`: Deep technical analysis
- `general-purpose`: Flexible research tasks

Projects can define custom agents in `.claude/agents/` for specialized behavior.

---

## Error Handling

If generation fails at any step:
1. Report which step failed
2. Show the error
3. Offer to retry just that step
4. Provide manual instructions if needed

---

## Validation

After generating all commands:
1. Check that all files were created
2. Validate markdown structure
3. Verify template variables were replaced
4. Confirm documentation directory exists
5. Present final status to user

Install Skill

SKILL.md

Workflow Generator Skill

Purpose

Template System

Template Path Resolution

Template Syntax

Execution Flow

Step 1: Discover Project Context

1.1 Detect Project Type

1.2 Check Existing Structure

1.3 Detect Build Tools

Step 2: Ask Customization Questions

Question 1: Elixir Project Type

Question 2: Test Strategy

Question 3: Documentation Location

Question 4: Quality Tools

Question 5: Planning Style

Question 6: WORKFLOWS.md Location

Step 3: Generate /research Command

Step 4: Generate /plan Command

Step 5: Generate /implement Command

Step 6: Generate /qa Command

Step 7: Generate /oneshot Command

Step 8: Generate /interview Command

Step 9: Create Documentation

9.1 Create Workflow README

/plan

/implement

/qa

Fix Workflow (Automatic)

Workflow Sequence

Customization

Project Configuration

Step 10: Present Usage Instructions

2. Create an Implementation Plan

3. Execute the Plan

4. Validate Implementation

Workflow Example

Customization

Re-generate Commands

Documentation

Next Steps