Create Workflow

You are tasked with helping users create new agents or commands by leveraging discovered patterns, templates, and examples from the workflow catalog.

Purpose

This command guides users through creating well-structured, standardized workflows by showing relevant examples and enforcing frontmatter consistency.

Initial Response

When invoked:

I'll help you create a new agent or command.

What would you like to create?
1. Agent (for Task tool sub-agents)
2. Command (for slash commands)

Or provide details:
- Name: (e.g., code-reviewer, test-generator)
- Purpose: (brief description)
- Similar to: (optional - name of existing workflow to model after)

Process

Step 1: Gather Requirements

Ask the user:

1. Type: Agent or Command?
2. Name: What should it be called? (suggest kebab-case)
3. Purpose: What does it do?
4. Tools needed: Which Claude Code tools will it use?
5. Category: Which category does it belong to?
6. Similar workflows: Any existing workflows to model after?

Step 2: Parallel Example Research

IMPORTANT: Spawn 3 parallel tasks to gather comprehensive examples.

Use TodoWrite to track parallel research.

Task 1 - Local Examples:

Use codebase-pattern-finder agent:
"Find all {agents/commands} in our workspace that are similar to {user-description}. Focus on {category} workflows. Return file paths and brief descriptions."

Tools: Glob, Grep, Read
Path: $(git rev-parse --show-toplevel)/plugins/
Return: List of similar local workflows with their frontmatter and key patterns

Task 2 - Catalog Examples:

Use thoughts-analyzer agent:
"Search the workflow catalog at thoughts/shared/workflows/ for workflows similar to {user-description}. Find examples from external repositories that match the {category} category."

Tools: Grep, Read
Path: thoughts/shared/workflows/
Return: External workflow examples with their implementations

Task 3 - Frontmatter Standards:

Use codebase-analyzer agent:
"Analyze all existing {agents/commands} in the workspace to extract the frontmatter standard. What fields are required? What patterns are used? What categories exist?"

Tools: Glob, Grep, Read
Path: $(git rev-parse --show-toplevel)/plugins/
Return: Frontmatter standard with field definitions and examples

WAIT for all 3 tasks to complete.

Step 3: Aggregate Examples

Combine results from parallel tasks:

• Local examples (Task 1)
• Catalog examples (Task 2)
• Frontmatter standards (Task 3)

Mark all tasks complete in TodoWrite.

Analyze:

1. Common patterns: What do similar workflows do?
2. Tool usage: Which tools are typically used?
3. Structure: How are they organized?
4. Frontmatter: What's the standard format?

Step 4: Present Options to User

Show analysis and options:

# Create {workflow-type}: {name}

## Similar Workflows Found

### From Our Workspace

1. **{local-workflow-1}**
   - Purpose: {description}
   - Tools: {tools}
   - File: {path}

2. **{local-workflow-2}** [....]

### From Catalog

1. **{external-workflow-1}** (from {repo})
   - Purpose: {description}
   - Tools: {tools}

## Frontmatter Standard

Based on existing workflows, here's the standard format:

```yaml
---
{ required-fields }
---
```

Recommended Approach

Based on similar workflows, I recommend:

• Model after: {most-similar-workflow}
• Tools to use: {suggested-tools}
• Key patterns: {patterns-to-follow}

Would you like me to:

1. Generate a workflow based on {specific-example}
2. Create a custom workflow from scratch
3. Show me more examples first

### Step 5: Generate Workflow Template

Based on user selection, generate the appropriate template:

#### 5a. For Agents

```markdown
---
name: {workflow-name}
description: |
  {Clear description from user input}

  Use this agent when:
  - {use case 1}
  - {use case 2}

  This agent will:
  - {action 1}
  - {action 2}
tools: {validated-tool-list}
model: inherit
category: {selected-category}
version: 1.0.0
---

# {Agent Name}

You are a specialized agent for {purpose}.

## Your Role

{Detailed role description}

## Process

### Step 1: {First Step}

{Instructions for first step}

### Step 2: {Second Step}

{Instructions for second step}

[Continue with all steps...]

## Output Format

Return your findings in this format:

{Expected output structure}

## Important Notes

- {Guideline 1}
- {Guideline 2}
- {Guideline 3}

## Examples

### Example 1: {Scenario}

**Input**: {example input}
**Expected output**: {example output}

[More examples...]

5b. For Commands

---
description: { One-line summary }
category: { category }
argument-hint: { if applicable }
tools: { tool-list }
model: inherit
version: 1.0.0
---

# {Command Name}

You are tasked with {command purpose}.

## Purpose

{Detailed explanation of what this command does and why it exists}

## Initial Response

When invoked:

\`\`\` {Default message to show user} \`\`\`

## Process

### Step 1: {First Step Name}

{Instructions for first step}

### Step 2: {Second Step Name}

{Instructions for second step}

[Continue with all steps...]

## Configuration

This command uses configuration from `.catalyst/config.json`:

```json
{
  "catalyst": {
    "project": {
      "ticketPrefix": "PROJ"
    }
  }
}
```

Advanced Usage

{Advanced Feature 1}

{Example usage}

{Advanced Feature 2}

{Example usage}

Important Notes

• {Guideline 1}
• {Guideline 2}

Integration with Other Commands

• {Related command 1}: {How they work together}
• {Related command 2}: {How they work together}

Error Handling

{Common Error 1}

• {How to handle it}

{Common Error 2}

• {How to handle it}

### Step 6: Validate Template

Before showing to user, validate:

1. **Frontmatter**:
   - All required fields present?
   - Tools list valid?
   - Category matches existing categories?
   - Name in kebab-case?
   - Version starts at 1.0.0?

2. **Structure**:
   - Clear purpose statement?
   - Step-by-step process?
   - Output format specified (for agents)?
   - Error handling included?

3. **Consistency**:
   - Matches patterns from similar workflows?
   - Uses workspace conventions?
   - References config.json for project-specific values?

If validation fails, fix issues before proceeding.

### Step 7: Present Draft

Show the user the generated template:

```markdown
# Generated Workflow: {name}

I've created a draft based on {source-pattern}.

**Type**: {Agent/Command}
**File**: {target-path}

## Frontmatter
```yaml
{frontmatter}

Key Features

• {Feature 1}
• {Feature 2}
• {Feature 3}

Modeled After

• Local: {local-example if any}
• External: {catalog-example if any}

Would you like me to:

1. Save this workflow as-is
2. Make adjustments (specify what to change)
3. Show me alternative approaches

### Step 8: Iterate on Feedback

Be ready to adjust:
- Add/remove steps
- Change tools
- Adjust frontmatter
- Modify structure
- Add examples
- Update descriptions

Continue iterating until user is satisfied.

### Step 9: Save Workflow

Determine save location:

**If Agent**:
- Save to: `plugins/dev/agents/{workflow-name}.md`

**If Skill**:
- Save to: `plugins/dev/skills/{workflow-name}/SKILL.md`

### Step 10: Create Creation Record

Save creation details to `thoughts/shared/workflows/created.md`:

```markdown
## {workflow-name}

- **Created**: {date}
- **Type**: {agent/command}
- **Location**: {file-path}
- **Modeled After**:
  - {local-example if any}
  - {catalog-example if any}
- **Purpose**: {brief-description}
- **Tools**: {tool-list}
- **Category**: {category}

**Creation Notes**: {any special notes about decisions made}

Step 11: Confirmation

Present success summary:

✅ Workflow created successfully!

**Saved to**: {file-path}

**What's included**:

- Standardized frontmatter
- Clear step-by-step process
- {Type-specif