commit 15898498901646545b6da5aeac81522b7bca58e8
Author: Zhongwei Li <lizhongwei.nkcs@gmail.com>
Date:   Sat Nov 29 18:14:41 2025 +0800

    Initial commit

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 0000000..bb694f9
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,13 @@
+{
+  "name": "catalyst-meta",
+  "description": "Workflow discovery and creation tools: learn from community patterns and extend Catalyst with new workflows.",
+  "version": "2.0.1",
+  "author": {
+    "name": "Coalesce Labs",
+    "email": "hello@coalesce.dev",
+    "url": "https://github.com/coalesce-labs"
+  },
+  "commands": [
+    "./commands"
+  ]
+}
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0f36168
--- /dev/null
+++ b/README.md
@@ -0,0 +1,3 @@
+# catalyst-meta
+
+Workflow discovery and creation tools: learn from community patterns and extend Catalyst with new workflows.
diff --git a/commands/create_workflow.md b/commands/create_workflow.md
new file mode 100644
index 0000000..6955500
--- /dev/null
+++ b/commands/create_workflow.md
@@ -0,0 +1,617 @@
+---
+description: Create new agents or commands using discovered patterns and templates
+category: workflow-discovery
+tools: Read, Write, Edit, Grep, Glob
+model: inherit
+version: 1.0.0
+workspace_only: true
+---
+
+# 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: /Users/ryan/code-repos/ryan-claude-workspace
+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: /Users/ryan/code-repos/ryan-claude-workspace/{agents,commands}/
+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:
+
+````markdown
+# 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
+
+````markdown
+---
+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 `.claude/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: `agents/{workflow-name}.md`
+
+**If Command**:
+- Save to: `commands/{workflow-name}.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:
+
+```markdown
+✅ Workflow created successfully!
+
+**Saved to**: {file-path}
+
+**What's included**:
+
+- Standardized frontmatter
+- Clear step-by-step process
+- {Type-specific features}
+- Error handling guidelines
+
+**Next steps**:
+
+1. Review: `{file-path}`
+2. Test: Try using the workflow
+3. Customize: Adjust for your specific needs
+4. Commit: `git add {file-path} && git commit -m "Add {workflow-name} {type}"`
+
+Creation recorded in: thoughts/shared/workflows/created.md
+```
+
+## Advanced Usage
+
+### Create from Catalog Entry
+
+```
+/create-workflow from catalog wshobson/commands/code-review
+```
+
+Creates a new workflow based on a specific catalog entry.
+
+### Create with Custom Template
+
+```
+/create-workflow agent data-analyzer --template minimal
+```
+
+Uses predefined templates:
+
+- `minimal`: Basic structure only
+- `standard`: Full featured (default)
+- `advanced`: Includes sub-agent patterns
+
+### Quick Create
+
+```
+/create-workflow command quick-commit "Create conventional commits"
+```
+
+Skips interactive steps, uses defaults.
+
+## Templates
+
+### Minimal Agent Template
+
+```yaml
+---
+name: {name}
+description: {description}
+tools: Read, Grep
+model: inherit
+category: general
+version: 1.0.0
+---
+
+# {Name}
+
+You are a specialized agent for {purpose}.
+
+## Process
+
+[Your implementation]
+
+## Output
+
+Return: {what you return}
+```
+
+### Minimal Command Template
+
+```yaml
+---
+description: {description}
+category: general
+tools: Read, Write
+model: inherit
+version: 1.0.0
+---
+
+# {Name}
+
+You are tasked with {purpose}.
+
+## Process
+
+[Your implementation]
+```
+
+## Categories
+
+Standard categories found in workspace:
+
+**For Agents**:
+
+- `research` - Finding and analyzing information
+- `analysis` - Deep code/data analysis
+- `search` - Locating files/patterns
+- `execution` - Running commands/operations
+- `validation` - Checking and verifying
+- `general` - Multi-purpose agents
+
+**For Commands**:
+
+- `workflow` - Development workflows
+- `planning` - Planning and design
+- `implementation` - Code changes
+- `validation` - Testing and verification
+- `linear` - Linear integration
+- `git` - Version control
+- `workflow-discovery` - Meta-workflows
+- `general` - Miscellaneous
+
+## Frontmatter Field Reference
+
+### Required for All
+
+- `description`: One-line summary (commands) or longer explanation (agents)
+- `tools`: Array of Claude Code tools used
+- `model`: Usually "inherit"
+- `version`: Start with "1.0.0"
+
+### Agent-Specific
+
+- `name`: Agent identifier in kebab-case
+- `category`: Agent category from list above
+
+### Command-Specific
+
+- `category`: Command category from list above
+- `argument-hint`: (optional) Hint for command arguments
+
+### Optional for Both
+
+- `source`: URL of origin if imported/adapted
+- `adapted`: Date if modified from external source
+- `original-author`: Credit for original creator
+
+## Important Notes
+
+- **Follow standards**: Always use workspace frontmatter format
+- **Validate tools**: Only reference tools that exist in Claude Code
+- **Check categories**: Use existing categories when possible
+- **Kebab-case names**: All workflow names should be kebab-case
+- **Clear descriptions**: Make purpose immediately obvious
+- **Include examples**: Show expected inputs/outputs for agents
+- **Error handling**: Always include error scenarios
+- **Configuration**: Use .claude/config.json for project values
+
+## Integration with Other Commands
+
+- **Discover**: `/discover-workflows` → find examples to model after
+- **Import**: `/import-workflow` → import external workflow as starting point
+- **Create**: `/create-workflow` (this command) → create new workflow
+- **Validate**: `/validate-frontmatter` → ensure consistency
+
+## Error Handling
+
+### No Similar Workflows Found
+
+- Show general templates
+- Ask for more details about desired functionality
+- Suggest browsing catalog manually
+
+### Invalid Tool References
+
+- List available tools
+- Suggest alternatives
+- Ask if should proceed without unavailable tools
+
+### Category Mismatch
+
+- Show list of existing categories
+- Suggest closest match
+- Allow creating new category if justified
+
+### Name Collision
+
+- Detect existing workflow with same name
+- Suggest alternative names
+- Ask: Rename / Replace / Cancel?
+
+This command helps you create high-quality workflows following workspace standards!
diff --git a/commands/discover_workflows.md b/commands/discover_workflows.md
new file mode 100644
index 0000000..b3dac40
--- /dev/null
+++ b/commands/discover_workflows.md
@@ -0,0 +1,367 @@
+---
+description: Research and catalog workflows from external Claude Code repositories
+category: workflow-discovery
+tools: mcp__deepwiki__ask_question, mcp__deepwiki__read_wiki_structure, Read, Write
+model: inherit
+version: 1.0.0
+workspace_only: true
+---
+
+# Discover Workflows
+
+You are tasked with researching external Claude Code repositories to discover, analyze, and catalog
+their agents, commands, and workflow patterns.
+
+## Purpose
+
+This command helps you learn from the Claude Code community by analyzing workflow repositories and
+extracting reusable patterns.
+
+## Supported Repositories
+
+Default repositories to research:
+
+- `catlog22/Claude-Code-Workflow` - Multi-agent automation
+- `automazeio/ccpm` - Project management system
+- `wshobson/commands` - Production slash commands
+- `wshobson/agents` - Production subagents
+- `qdhenry/Claude-Command-Suite` - 148+ commands, 54 agents
+- `VoltAgent/awesome-claude-code-subagents` - 100+ subagents
+- `hesreallyhim/awesome-claude-code` - Curated commands/agents
+- `feiskyer/claude-code-settings` - Workflow improvements
+- `OneRedOak/claude-code-workflows` - Code review workflows
+- `anthropics/claude-code` - Official Claude Code repo
+- `winfunc/opcode` - GUI toolkit for agents/commands
+
+## Initial Response
+
+When invoked:
+
+```
+I'll research Claude Code workflows from external repositories.
+
+Which repository would you like to explore?
+1. wshobson/commands - Production slash commands
+2. wshobson/agents - Production subagents
+3. qdhenry/Claude-Command-Suite - 148+ commands
+4. VoltAgent/awesome-claude-code-subagents - 100+ subagents
+5. Custom repository (provide org/repo)
+
+Or type 'all' to catalog all supported repos (this may take a while).
+```
+
+## Process
+
+### Step 1: Select Repository
+
+Get user selection or use provided parameter.
+
+### Step 2: Research Repository (Parallel Sub-Agents)
+
+**IMPORTANT**: Spawn 3 parallel research tasks for efficiency and context isolation.
+
+Use TodoWrite to track the 3 parallel research tasks.
+
+**Task 1 - Workflow Discovery**:
+
+```
+Use external-research agent:
+"Research {repo-name}. What commands and agents are available? List all workflows with brief descriptions of what each does."
+
+Tools: mcp__deepwiki__read_wiki_structure, mcp__deepwiki__ask_question
+Return: Complete list of all workflows found
+```
+
+**Task 2 - Frontmatter Analysis**:
+
+```
+Use external-research agent:
+"Research {repo-name}. What frontmatter format is used for agents and commands? Provide specific examples showing all frontmatter fields used."
+
+Tools: mcp__deepwiki__ask_question
+Return: Frontmatter patterns with concrete examples
+```
+
+**Task 3 - Implementation Patterns**:
+
+```
+Use external-research agent:
+"Research {repo-name}. What are the common implementation patterns, structures, and conventions used across workflows? Include naming conventions, file organization, and any templates."
+
+Tools: mcp__deepwiki__ask_question
+Return: Patterns, templates, conventions observed
+```
+
+**WAIT for all 3 tasks to complete before proceeding.**
+
+**Why parallel**:
+
+- 3x faster than sequential
+- Each agent has isolated context
+- No context contamination between research areas
+- Better token efficiency per agent
+
+### Step 3: Aggregate Parallel Results
+
+Combine findings from the 3 parallel research tasks:
+
+- Workflows list from Task 1
+- Frontmatter patterns from Task 2
+- Implementation patterns from Task 3
+
+Mark all 3 tasks complete in TodoWrite.
+
+### Step 4: Analyze and Extract
+
+From the aggregated results, extract:
+
+1. **Available Workflows**
+   - List all agents and commands
+   - What each one does
+   - When to use them
+
+2. **Frontmatter Patterns**
+   - What fields are used
+   - Naming conventions
+   - Tool specifications
+   - Categories/tags
+
+3. **Implementation Patterns**
+   - Common structures
+   - Reusable templates
+   - Integration patterns
+
+4. **Unique Features**
+   - Novel approaches
+   - Interesting combinations
+   - Advanced techniques
+
+### Step 5: Create Catalog Entry
+
+Save research to `thoughts/shared/workflows/{repo-name}/analysis.md`:
+
+````markdown
+# Workflow Analysis: {Repo Name}
+
+**Repository**: {org/repo} **Analyzed**: {date} **Focus**: {agents/commands/both}
+
+## Summary
+
+[1-2 sentence overview of what this repo offers]
+
+## Available Workflows
+
+### Commands
+
+1. **{command-name}**
+   - **Purpose**: [what it does]
+   - **Use when**: [scenario]
+   - **Frontmatter**:
+     ```yaml
+     [actual frontmatter from repo]
+     ```
+
+2. **{command-name}** [...]
+
+### Agents
+
+1. **{agent-name}**
+   - **Purpose**: [what it does]
+   - **Tools**: [tools it uses]
+   - **Frontmatter**:
+     ```yaml
+     [actual frontmatter from repo]
+     ```
+
+## Frontmatter Patterns
+
+### Standard Fields
+
+- name: [how they define it]
+- description: [format they use]
+- tools: [how specified]
+- [other fields observed]
+
+### Naming Conventions
+
+- [pattern 1]
+- [pattern 2]
+
+## Implementation Patterns
+
+### Common Structures
+
+[Patterns you notice across workflows]
+
+### Reusable Templates
+
+[Templates that could be adapted]
+
+## Unique Features
+
+[Novel or interesting approaches]
+
+## Integration Notes
+
+[How these could integrate with your workspace]
+
+## Recommendations
+
+### High-Value Imports
+
+1. **{workflow-name}** - [why it's valuable]
+2. **{workflow-name}** - [why it's valuable]
+
+### Patterns to Adopt
+
+- [Pattern 1]: [how to use it]
+- [Pattern 2]: [how to use it]
+
+## References
+
+- DeepWiki searches: [links]
+- Repository: {URL}
+- Analyzed on: {date}
+````
+
+### Step 6: Update Master Catalog
+
+Update `thoughts/shared/workflows/catalog.md`:
+
+```markdown
+# Workflow Catalog
+
+Discovered workflows from the Claude Code community.
+
+## Repositories Analyzed
+
+### wshobson/commands
+
+- **Analyzed**: 2025-01-08
+- **Workflows**: 15 commands
+- **Focus**: Production-ready automation
+- **Details**: [See analysis](wshobson-commands/analysis.md)
+- **Top Picks**:
+  - code-review: Automated code review workflow
+  - refactor: Safe refactoring patterns
+
+[... more repos]
+
+## By Category
+
+### Code Review
+
+- wshobson/commands: code-review
+- OneRedOak/claude-code-workflows: review-pr
+
+### Documentation
+
+- qdhenry/Claude-Command-Suite: doc-generator
+- hesreallyhim/awesome-claude-code: readme-generator
+
+[... more categories]
+
+## By Use Case
+
+### "I want to automate code reviews"
+
+1. wshobson/commands/code-review
+2. OneRedOak/claude-code-workflows/review-pr
+3. [Details in respective analyses]
+
+### "I need project management workflows"
+
+1. automazeio/ccpm - Full PM system
+2. [...]
+```
+
+### Step 7: Present Summary
+
+Show user what was found:
+
+```markdown
+# Discovery Results: {Repo Name}
+
+## Summary
+
+Discovered {N} workflows ({X} commands, {Y} agents)
+
+## Highlights
+
+### Top Workflows
+
+1. **{name}** - {brief description}
+2. **{name}** - {brief description}
+3. **{name}** - {brief description}
+
+### Interesting Patterns
+
+- {Pattern 1}
+- {Pattern 2}
+
+### Recommended for Import
+
+- **{workflow-name}**: {why}
+
+## Next Steps
+
+1. **Review the analysis**: `thoughts/shared/workflows/{repo}/analysis.md`
+2. **Import a workflow**: `/import-workflow {repo} {workflow-name}`
+3. **Discover another repo**: `/discover-workflows`
+
+Catalog updated at: `thoughts/shared/workflows/catalog.md`
+```
+
+## Advanced Usage
+
+### Discover All Repos (Maximum Parallelism)
+
+```
+/discover-workflows all
+```
+
+This will:
+
+1. Spawn parallel research for ALL supported repos simultaneously
+2. Each repo gets 3 sub-agents (structure, frontmatter, patterns)
+3. Total: 11 repos × 3 agents = 33 parallel tasks
+4. Aggregate all results
+5. Create analysis for each repo
+6. Update master catalog
+7. Present summary comparison
+
+**Performance**: ~10-15x faster than sequential research
+
+**Context efficiency**: Each agent loads only its research area
+
+### Discover Custom Repo
+
+```
+/discover-workflows org/repo
+```
+
+Works with any public GitHub repo with Claude Code workflows.
+
+### Focus on Specific Type
+
+```
+/discover-workflows wshobson/agents --focus agents
+```
+
+Only analyzes agents, skips commands.
+
+## Important Notes
+
+- **Read-only**: This command only researches, doesn't import
+- **Catalog persistence**: Saved in thoughts/ for future reference
+- **Reusable**: Run anytime to update catalog
+- **Combinable**: Use with `/import-workflow` to actually import
+
+## Integration with Other Commands
+
+- **Discover** → `/discover-workflows` (this command)
+- **Import** → `/import-workflow` (imports discovered workflows)
+- **Create** → `/create-workflow` (creates new using discovered patterns)
+- **Validate** → `/validate-frontmatter` (ensures consistency)
+
+This command is the first step in workflow discovery and reuse!
diff --git a/commands/import_workflow.md b/commands/import_workflow.md
new file mode 100644
index 0000000..ba4f488
--- /dev/null
+++ b/commands/import_workflow.md
@@ -0,0 +1,347 @@
+---
+description: Import and adapt a workflow from external repositories
+category: workflow-discovery
+tools: Read, Write, Edit, mcp__deepwiki__ask_question
+model: inherit
+version: 1.0.0
+workspace_only: true
+---
+
+# Import Workflow
+
+You are tasked with importing and adapting workflows from external Claude Code repositories into
+this workspace.
+
+## Purpose
+
+This command helps you import discovered workflows, adapt them to your workspace standards, validate
+frontmatter consistency, and integrate with your configuration.
+
+## Initial Response
+
+When invoked:
+
+```
+I'll help you import a workflow from an external repository.
+
+Please provide:
+1. Repository name (e.g., wshobson/commands)
+2. Workflow name (e.g., code-review)
+
+Or, if you've already run /discover-workflows:
+- Check the catalog: thoughts/shared/workflows/catalog.md
+- Pick from discovered workflows
+```
+
+## Process
+
+### Step 1: Identify Workflow
+
+Get the repository and workflow name from user or parameters.
+
+### Step 2: Parallel Research & Validation
+
+**IMPORTANT**: Spawn 3 parallel tasks for comprehensive analysis.
+
+Use TodoWrite to track parallel research.
+
+**Task 1 - External Research**:
+
+```
+Use external-research agent:
+"Research {repo}/{workflow}. Explain what this workflow does, how it works, what tools it uses, and provide the complete implementation including frontmatter."
+
+Tools: mcp__deepwiki__ask_question
+Return: Full workflow understanding and implementation
+```
+
+**Task 2 - Local Pattern Check**:
+
+```
+Use codebase-pattern-finder agent:
+"Find similar workflows in our workspace (agents/ and commands/ directories). Look for workflows that serve similar purposes or use similar patterns."
+
+Tools: Grep, Glob, Read
+Path: /Users/ryan/code-repos/ryan-claude-workspace
+Return: Similar local workflows for comparison
+```
+
+**Task 3 - Historical Context**:
+
+```
+Use thoughts-locator agent:
+"Search for any previous research, notes, or attempts related to this type of workflow. Search for keywords: {workflow-name}, {workflow-purpose}."
+
+Tools: Grep, Glob
+Path: thoughts/
+Return: Any historical context or previous attempts
+```
+
+**WAIT for all 3 tasks to complete.**
+
+### Step 3: Aggregate and Analyze
+
+Combine results from parallel tasks:
+
+- External workflow details (Task 1)
+- Similar local patterns (Task 2)
+- Historical context (Task 3)
+
+Mark all tasks complete in TodoWrite.
+
+Analyze:
+
+1. **Purpose alignment**: Does this fit our needs?
+2. **Duplication check**: Do we already have something similar?
+3. **Adaptation needs**: What needs to change?
+
+### Step 4: Present Analysis to User
+
+Show comprehensive analysis:
+
+````markdown
+# Import Analysis: {workflow-name}
+
+## What It Does
+
+[Summary from external research]
+
+## External Implementation
+
+- **Repository**: {repo}
+- **Tools used**: [list]
+- **Frontmatter**:
+  ```yaml
+  [original frontmatter]
+  ```
+````
+
+## Comparison with Our Workspace
+
+### Similar Local Workflows
+
+[From Task 2 - what we already have]
+
+### Differences
+
+- [Key differences from our patterns]
+
+### Historical Context
+
+[From Task 3 - any previous attempts or notes]
+
+## Required Adaptations
+
+1. **Frontmatter**: [what needs to change]
+2. **Configuration**: [ticket prefix, Linear IDs, etc.]
+3. **Tool references**: [any tool updates needed]
+4. **Naming**: [follow our conventions]
+
+## Recommendation
+
+[Import as-is / Import with modifications / Skip (we have similar)]
+
+Proceed with import? (Y/n)
+
+````
+
+### Step 5: Adapt to Workspace Standards
+
+If user approves, adapt the workflow:
+
+#### 5a. Standardize Frontmatter
+
+Apply consistent frontmatter based on type:
+
+**For Agents**:
+```yaml
+---
+name: {workflow-name}
+description: |
+  {Clear description from research}
+  {When to invoke}
+tools: {validated tool list}
+model: inherit
+category: {appropriate category}
+version: 1.0.0
+source: {repo-url}  # Track origin
+---
+````
+
+**For Commands**:
+
+```yaml
+---
+description: { One-line summary }
+category: { appropriate category }
+argument-hint: { if applicable }
+tools: { tool list }
+model: inherit
+version: 1.0.0
+source: { repo-url } # Track origin
+---
+```
+
+#### 5b. Replace Repository-Specific Values
+
+Check for and replace:
+
+- Ticket prefixes (ENG-XXX → read from `.claude/config.json`)
+- Repository paths (their paths → local paths)
+- Team/project IDs (their IDs → prompt or use config)
+- User names (their names → generic or config)
+- Tool names (check compatibility)
+
+#### 5c. Add Attribution
+
+Add source attribution in frontmatter and as comment:
+
+```markdown
+---
+source: https://github.com/{repo}
+adapted: { date }
+original-author: { if known }
+---
+
+<!--
+Adapted from: {repo}/{workflow-name}
+Original: {URL}
+Modifications:
+- {change 1}
+- {change 2}
+-->
+```
+
+### Step 6: Validate Frontmatter
+
+Before saving, validate against standard:
+
+- Required fields present?
+- Tools list valid?
+- Category appropriate?
+- Description clear?
+- Name follows kebab-case?
+
+If validation fails, show issues and fix.
+
+### Step 7: Save Workflow
+
+Determine type and save location:
+
+**If Agent**:
+
+- Save to: `agents/{workflow-name}.md`
+
+**If Command**:
+
+- Save to: `commands/{workflow-name}.md`
+
+### Step 8: Create Import Record
+
+Save import details to `thoughts/shared/workflows/imports.md`:
+
+```markdown
+## {workflow-name}
+
+- **Imported**: {date}
+- **Source**: {repo}/{workflow}
+- **Type**: {agent/command}
+- **Location**: {file-path}
+- **Adaptations**:
+  - {adaptation 1}
+  - {adaptation 2}
+- **Status**: Active
+
+**Why imported**: {reason}
+```
+
+### Step 9: Confirmation
+
+Present success summary:
+
+```markdown
+✅ Workflow imported successfully!
+
+**Saved to**: {file-path}
+
+**Adaptations made**:
+
+- Standardized frontmatter
+- Updated ticket prefix: ENG → PROJ
+- Added source attribution
+- Validated tools list
+
+**Next steps**:
+
+1. Review: `{file-path}`
+2. Test: Try using the workflow
+3. Customize: Adjust for your specific needs
+4. Commit: `git add {file-path} && git commit -m "Import {workflow-name} from {repo}"`
+
+Import recorded in: thoughts/shared/workflows/imports.md
+```
+
+## Advanced Usage
+
+### Import with Custom Adaptations
+
+```
+/import-workflow wshobson/commands code-review --adapt "Use our custom linting rules"
+```
+
+### Import Multiple Workflows
+
+```
+/import-workflow wshobson/commands code-review refactor test-gen
+```
+
+Imports all 3 in sequence (with parallel validation for each).
+
+### Dry Run Mode
+
+```
+/import-workflow wshobson/commands code-review --dry-run
+```
+
+Shows what would be imported without actually saving files.
+
+## Important Notes
+
+- **Always validate**: Never blindly import without checking compatibility
+- **Track provenance**: Always attribute source
+- **Respect licenses**: Check repo license before importing
+- **Test imported workflows**: Verify they work in your environment
+- **Keep imports.md updated**: Track what you've imported
+
+## Integration with Other Commands
+
+- **Discover first**: `/discover-workflows` → catalog workflows
+- **Then import**: `/import-workflow` (this command)
+- **Validate**: `/validate-frontmatter` ensures consistency
+- **Create custom**: `/create-workflow` for new workflows
+
+## Error Handling
+
+### Workflow Not Found
+
+- Suggest running `/discover-workflows {repo}` first
+- Check catalog for available workflows
+
+### Incompatible Tools
+
+- List tools that don't exist in your environment
+- Suggest alternatives
+- Ask if should proceed with modifications
+
+### Duplicate Workflow
+
+- Show existing similar workflow
+- Ask: Replace / Rename / Skip?
+
+### Validation Failures
+
+- Show specific issues
+- Offer to auto-fix
+- Request manual review if complex
+
+This command bridges external workflows into your workspace with proper adaptation and validation!
diff --git a/commands/validate_frontmatter.md b/commands/validate_frontmatter.md
new file mode 100644
index 0000000..d76e5bd
--- /dev/null
+++ b/commands/validate_frontmatter.md
@@ -0,0 +1,666 @@
+---
+description: Validate and fix frontmatter consistency across all workflows
+category: workflow-discovery
+tools: Read, Edit, Glob, Grep
+model: inherit
+version: 1.0.0
+workspace_only: true
+---
+
+# Validate Frontmatter
+
+You are tasked with validating frontmatter consistency across all agents and commands in the
+workspace, and fixing any issues found.
+
+## Purpose
+
+This command ensures all workflows follow the workspace frontmatter standard, making them easier to
+maintain, discover, and integrate.
+
+## Initial Response
+
+When invoked:
+
+```
+I'll validate frontmatter across all workflows.
+
+Checking:
+- agents/ directory
+- commands/ directory
+
+What would you like to do?
+1. Validate all workflows (report issues only)
+2. Validate and auto-fix issues
+3. Validate specific workflow
+4. Generate frontmatter standard document
+```
+
+## Process
+
+### Step 1: Determine Scope
+
+Get user selection:
+
+- **All workflows**: Check everything
+- **Auto-fix**: Fix issues automatically
+- **Specific workflow**: Validate one file
+- **Generate standard**: Create reference document
+
+### Step 2: Parallel Validation
+
+**IMPORTANT**: Spawn parallel validation tasks for efficiency.
+
+Use TodoWrite to track parallel validation tasks.
+
+**For "Validate All" mode**:
+
+**Task 1 - Validate Agents**:
+
+```
+Use codebase-analyzer agent:
+"Validate frontmatter in all files matching agents/*.md. For each file, check:
+1. Required fields present (name, description, tools, model, version)
+2. Name field matches filename (kebab-case)
+3. Tools list contains valid Claude Code tools
+4. Category is one of: research, analysis, search, execution, validation, general
+5. Version follows semver (e.g., 1.0.0)
+6. Description is clear and informative
+Return: List of all validation issues found with file:line references"
+
+Tools: Glob, Grep, Read
+Path: /Users/ryan/code-repos/ryan-claude-workspace/agents/
+Return: Validation report for all agents
+```
+
+**Task 2 - Validate Commands**:
+
+```
+Use codebase-analyzer agent:
+"Validate frontmatter in all files matching commands/*.md. For each file, check:
+1. Required fields present (description, category, tools, model, version)
+2. No 'name' field (commands use filename)
+3. Tools list contains valid Claude Code tools
+4. Category is one of: workflow, planning, implementation, validation, linear, git, workflow-discovery, general
+5. Version follows semver (e.g., 1.0.0)
+6. Description is clear and concise
+7. argument-hint present if command takes arguments
+Return: List of all validation issues found with file:line references"
+
+Tools: Glob, Grep, Read
+Path: /Users/ryan/code-repos/ryan-claude-workspace/commands/
+Return: Validation report for all commands
+```
+
+**Task 3 - Extract Tool References**:
+
+```
+Use codebase-pattern-finder agent:
+"Extract all unique tool names referenced in frontmatter across agents/*.md and commands/*.md. Return a sorted list of all tools used."
+
+Tools: Glob, Grep
+Path: /Users/ryan/code-repos/ryan-claude-workspace/
+Return: Complete list of tools referenced
+```
+
+**WAIT for all 3 tasks to complete.**
+
+### Step 3: Aggregate Validation Results
+
+Combine results from parallel tasks:
+
+- Agent issues (Task 1)
+- Command issues (Task 2)
+- Tool inventory (Task 3)
+
+Mark all tasks complete in TodoWrite.
+
+Analyze:
+
+1. **Critical issues**: Missing required fields, invalid formats
+2. **Warnings**: Unusual patterns, potential improvements
+3. **Tool usage**: Are all tools valid?
+4. **Category distribution**: Are categories being used correctly?
+
+### Step 4: Present Validation Report
+
+Show comprehensive report:
+
+```markdown
+# Frontmatter Validation Report
+
+**Validated**: {date} **Scope**: {agents-count} agents, {commands-count} commands **Status**:
+{PASS/FAIL}
+
+## Summary
+
+- ✅ **Passed**: {pass-count} workflows
+- ⚠️ **Warnings**: {warning-count} workflows
+- ❌ **Failed**: {fail-count} workflows
+
+## Critical Issues
+
+### {workflow-name}.md
+
+- ❌ Missing required field: `version`
+- ❌ Invalid category: "misc" (should be one of: general, research, analysis...)
+
+### {workflow-name}.md
+
+- ❌ Name field "{name}" doesn't match filename "{filename}"
+- ❌ Invalid tool reference: "SearchFiles" (not a valid Claude Code tool)
+
+## Warnings
+
+### {workflow-name}.md
+
+- ⚠️ Description is very short (< 20 chars)
+- ⚠️ No category specified (defaulting to "general")
+
+### {workflow-name}.md
+
+- ⚠️ Using old version format: "v1.0" (should be "1.0.0")
+
+## Tool Inventory
+
+**Total unique tools**: {tool-count} **Valid tools**: {valid-count} **Invalid references**:
+{invalid-count}
+
+### Used Tools:
+
+- Read ({usage-count} workflows)
+- Write ({usage-count} workflows)
+- Edit ({usage-count} workflows)
+- Grep ({usage-count} workflows)
+- Glob ({usage-count} workflows) [... more tools ...]
+
+### Invalid References:
+
+- SearchFiles (used in {workflow-name}.md) → Should be: Grep or Glob
+- FindFile (used in {workflow-name}.md) → Should be: Glob
+
+## Category Distribution
+
+### Agents:
+
+- research: {count}
+- analysis: {count}
+- search: {count}
+- execution: {count}
+- validation: {count}
+- general: {count}
+
+### Commands:
+
+- workflow: {count}
+- planning: {count}
+- implementation: {count}
+- validation: {count}
+- linear: {count}
+- git: {count}
+- workflow-discovery: {count}
+- general: {count}
+
+## Recommendations
+
+1. **Fix critical issues first**: {count} workflows need immediate attention
+2. **Standardize versions**: {count} workflows use non-semver format
+3. **Update tool references**: {count} invalid tool names found
+4. **Add descriptions**: {count} workflows have minimal descriptions
+
+---
+
+Next steps:
+
+- Run with `--fix` to auto-correct issues
+- Review and approve fixes before applying
+- Re-validate after fixes
+```
+
+### Step 5: Auto-Fix Mode (if requested)
+
+If user chose auto-fix:
+
+1. **Create fix plan**:
+   - List all fixable issues
+   - Show what will be changed
+   - Ask for confirmation
+
+2. **Present fix plan**:
+
+   ```markdown
+   # Auto-Fix Plan
+
+   I can automatically fix {fixable-count} issues:
+
+   ## {workflow-name}.md
+
+   - Add missing `version: 1.0.0`
+   - Fix category: "misc" → "general"
+   - Standardize tool name: "SearchFiles" → "Grep"
+
+   ## {workflow-name}.md
+
+   - Fix version format: "v1.0" → "1.0.0"
+   - Add missing `model: inherit`
+
+   **Cannot auto-fix** ({manual-count} issues):
+
+   - {workflow-name}.md: Description too short (needs human review)
+   - {workflow-name}.md: Unclear category (analysis vs research?)
+
+   Proceed with auto-fix? (Y/n)
+   ```
+
+3. **Apply fixes** (after confirmation):
+   - Use Edit tool to fix each issue
+   - Track all changes made
+   - Preserve original formatting and comments
+
+4. **Report results**:
+
+   ```markdown
+   ✅ Auto-fix complete!
+
+   **Fixed**: {fixed-count} issues across {file-count} files
+
+   ### Changes Made:
+
+   #### agents/codebase-locator.md
+
+   - Added `version: 1.0.0`
+   - Standardized category: "search"
+
+   #### commands/create_plan.md
+
+   - Fixed version: "v1.0" → "1.0.0"
+   - Updated tool reference: "SearchFiles" → "Grep"
+
+   [... more changes ...]
+
+   **Still needs manual review**:
+
+   - {workflow-name}.md: {issue description}
+
+   Re-run validation to verify: `/validate-frontmatter`
+   ```
+
+### Step 6: Generate Standard Document (if requested)
+
+If user chose to generate standard:
+
+Create `docs/FRONTMATTER_STANDARD.md`:
+
+````markdown
+# Frontmatter Standard
+
+This document defines the frontmatter standard for all agents and commands in this workspace.
+
+## Agent Frontmatter
+
+### Required Fields
+
+```yaml
+---
+name: { agent-name } # Agent identifier (kebab-case, must match filename)
+description: | # Multi-line description
+  {What this agent does}
+
+  Use this agent when:
+  - {Use case 1}
+  - {Use case 2}
+tools: { tool-list } # Array of Claude Code tools
+model: inherit # Always "inherit"
+category: { category } # One of: research, analysis, search, execution, validation, general
+version: 1.0.0 # Semantic version
+---
+```
+````
+
+### Optional Fields
+
+```yaml
+source: { repo-url } # If imported/adapted
+adapted: { date } # Date of adaptation
+original-author: { name } # Original creator
+```
+
+### Valid Categories
+
+- **research**: Finding and gathering information
+- **analysis**: Deep code/data analysis
+- **search**: Locating files/patterns/content
+- **execution**: Running commands/operations
+- **validation**: Checking and verifying
+- **general**: Multi-purpose or uncategorized
+
+### Example
+
+```yaml
+---
+name: codebase-analyzer
+description: |
+  Analyzes codebases to understand implementation details and patterns.
+
+  Use this agent when:
+  - You need to understand how a feature is implemented
+  - You want to trace data flow through the system
+  - You need to find patterns and conventions
+tools: Read, Grep, Glob
+model: inherit
+category: analysis
+version: 1.0.0
+---
+```
+
+## Command Frontmatter
+
+### Required Fields
+
+```yaml
+---
+description: { one-line-summary } # Brief description (no name field!)
+category: { category } # Command category
+tools: { tool-list } # Array of Claude Code tools
+model: inherit # Always "inherit"
+version: 1.0.0 # Semantic version
+---
+```
+
+### Optional Fields
+
+```yaml
+argument-hint: { hint } # Hint for command arguments
+source: { repo-url } # If imported/adapted
+adapted: { date } # Date of adaptation
+original-author: { name } # Original creator
+```
+
+### Valid Categories
+
+- **workflow**: Development workflows
+- **planning**: Planning and design
+- **implementation**: Code changes
+- **validation**: Testing and verification
+- **linear**: Linear integration
+- **git**: Version control
+- **workflow-discovery**: Meta-workflows
+- **general**: Miscellaneous
+
+### Example
+
+```yaml
+---
+description: Create detailed implementation plans through interactive process
+category: planning
+argument-hint: [ticket-file | ticket-reference]
+tools: Read, Write, Edit, Grep, Glob, Task, TodoWrite
+model: inherit
+version: 1.0.0
+---
+```
+
+## Valid Tools
+
+Claude Code provides these tools:
+
+### File Operations
+
+- `Read` - Read file contents
+- `Write` - Write files
+- `Edit` - Edit existing files
+
+### Search
+
+- `Grep` - Search file contents (regex)
+- `Glob` - Find files by pattern
+
+### Execution
+
+- `Bash` - Run shell commands
+- `Task` - Spawn sub-agents
+
+### Management
+
+- `TodoWrite` - Manage todo lists
+
+### External
+
+- `WebFetch` - Fetch web content
+- `WebSearch` - Search the web
+- `mcp__deepwiki__ask_question` - Query external repos
+- `mcp__deepwiki__read_wiki_structure` - Get repo structure
+- `mcp__deepwiki__read_wiki_contents` - Read repo docs
+
+### Linear Integration
+
+- `linear_get_ticket` - Get Linear ticket details
+- `linear_create_ticket` - Create Linear tickets
+- `linear_update_ticket` - Update Linear tickets
+
+(Check official Claude Code docs for complete list)
+
+## Validation Rules
+
+### All Workflows
+
+1. **Required fields must be present**
+2. **Version must follow semver**: `X.Y.Z` (not `vX.Y`)
+3. **Model must be "inherit"** (unless specific reason)
+4. **Tools must be valid Claude Code tools**
+5. **Category must be from valid list**
+
+### Agents Specifically
+
+1. **Must have `name` field** matching filename
+2. **Name must be kebab-case**
+3. **Description should be multi-line with use cases**
+
+### Commands Specifically
+
+1. **Must NOT have `name` field** (use filename)
+2. **Description should be one-line summary**
+3. **Use `argument-hint` if command takes arguments**
+
+## Common Mistakes
+
+### ❌ Wrong: Command with name field
+
+```yaml
+---
+name: create-plan # Commands don't have name field
+description: Create plans
+---
+```
+
+### ✅ Correct: Command without name
+
+```yaml
+---
+description: Create detailed implementation plans
+category: planning
+---
+```
+
+### ❌ Wrong: Invalid tool reference
+
+```yaml
+tools: SearchFiles, FindFile # These aren't real tools
+```
+
+### ✅ Correct: Valid tools
+
+```yaml
+tools: Grep, Glob # Correct tool names
+```
+
+### ❌ Wrong: Version format
+
+```yaml
+version: v1.0 # Should be semver
+```
+
+### ✅ Correct: Semver version
+
+```yaml
+version: 1.0.0 # Proper semver
+```
+
+## Updating the Standard
+
+When adding new categories or patterns:
+
+1. Update this document
+2. Validate all existing workflows
+3. Fix any inconsistencies
+4. Document the change in git commit
+
+## See Also
+
+- `/validate-frontmatter` - Validate workflows against this standard
+- `/create-workflow` - Create new workflows with correct frontmatter
+- `/import-workflow` - Import external workflows and adapt frontmatter
+
+```
+
+Save and report:
+```
+
+✅ Frontmatter standard documented!
+
+**Saved to**: docs/FRONTMATTER_STANDARD.md
+
+This document now serves as the canonical reference for all frontmatter in this workspace.
+
+Next steps:
+
+1. Review the standard
+2. Share with team
+3. Use `/validate-frontmatter` to check compliance
+4. Reference when creating new workflows
+
+```
+
+## Advanced Usage
+
+### Validate Specific Workflow
+
+```
+
+/validate-frontmatter agents/codebase-analyzer.md
+
+```
+
+Validates just one file.
+
+### Auto-Fix Everything
+
+```
+
+/validate-frontmatter --fix
+
+```
+
+Automatically fixes all issues without prompting.
+
+### Generate Report Only
+
+```
+
+/validate-frontmatter --report-only > frontmatter-report.md
+
+```
+
+Saves report to file for review.
+
+### Validate by Category
+
+```
+
+/validate-frontmatter --category research
+
+```
+
+Only validates workflows in "research" category.
+
+## Validation Categories
+
+### Critical Issues (Must Fix)
+
+- Missing required fields
+- Invalid field values
+- Name/filename mismatch (agents)
+- Invalid tool references
+- Malformed YAML
+
+### Warnings (Should Fix)
+
+- Short descriptions (< 20 chars)
+- Missing optional but recommended fields
+- Unusual category choices
+- Non-standard patterns
+
+### Info (Nice to Have)
+
+- Could add more detail
+- Could specify argument-hint
+- Could add source attribution
+- Could improve formatting
+
+## Auto-Fix Capabilities
+
+### What Can Be Auto-Fixed
+
+✅ Missing version field → Add `version: 1.0.0`
+✅ Wrong version format → Convert to semver
+✅ Missing model field → Add `model: inherit`
+✅ Common tool typos → Fix to correct names
+✅ Category typos → Fix to valid category
+✅ YAML formatting → Standardize indentation
+
+### What Requires Manual Review
+
+❌ Ambiguous categories → Needs human judgment
+❌ Short descriptions → Needs content creation
+❌ Complex tool issues → May need workflow redesign
+❌ Missing description → Needs understanding of purpose
+
+## Important Notes
+
+- **Non-destructive**: Auto-fix preserves content, only fixes frontmatter
+- **Safe**: Always shows plan before applying fixes
+- **Trackable**: Reports all changes made
+- **Reversible**: Changes are standard edits, can be reverted via git
+- **Standard-based**: Uses workspace-specific conventions
+
+## Integration with Other Commands
+
+- **Discover**: `/discover-workflows` → uses this for validation
+- **Import**: `/import-workflow` → validates imported workflows
+- **Create**: `/create-workflow` → ensures new workflows are valid
+- **Validate**: `/validate-frontmatter` (this command) → checks everything
+
+## Error Handling
+
+### Malformed YAML
+- Report syntax errors
+- Show line number
+- Suggest fixes
+- Cannot auto-fix (manual correction needed)
+
+### Unknown Fields
+- Report unexpected fields
+- Ask: Keep / Remove?
+- Could be custom extensions
+
+### Missing Files
+- Skip files that don't exist
+- Report which files were skipped
+- Continue validation
+
+### Permission Errors
+- Report read/write issues
+- Skip files that can't be accessed
+- Provide error details
+
+This command ensures workspace consistency and quality!
+```
diff --git a/commands/workflow_help.md b/commands/workflow_help.md
new file mode 100644
index 0000000..cfca98a
--- /dev/null
+++ b/commands/workflow_help.md
@@ -0,0 +1,592 @@
+---
+description: Interactive guide to supported workflows with context-aware assistance
+category: workflow
+tools: Read, Grep, Glob, Task
+model: inherit
+version: 1.0.0
+---
+
+# Workflow Help
+
+You are an interactive workflow guide that helps users navigate the supported workflows in this
+repository using parallel sub-agents for research and context-aware guidance.
+
+## Initial Response
+
+When this command is invoked WITHOUT parameters:
+
+```
+# 🎯 Workflow Guide
+
+I can help you navigate the supported workflows in this workspace.
+
+## Available Workflows
+
+**1. Development Workflow** (research → plan → implement → validate → PR)
+   - `/research-codebase` → Document existing system
+   - `/create-plan` → Create implementation plan
+   - `/implement-plan` → Execute approved plan
+   - `/validate-plan` → Verify implementation
+   - Handoffs & worktrees for context management
+
+**2. Workflow Discovery** (discover → import → create → validate)
+   - `/discover-workflows` → Research external repositories
+   - `/import-workflow` → Adapt external workflows
+   - `/create-workflow` → Build new agents/commands
+   - `/validate-frontmatter` → Ensure consistency
+
+**3. Utilities**
+   - `/catalyst-dev:commit` → Create structured commits
+   - `/describe-pr` → Generate PR descriptions
+   - `/catalyst-dev:debug` → Investigate issues
+   - `/catalyst-dev:linear` → Linear ticket integration
+
+---
+
+**Which workflow would you like to learn about?**
+
+Type the number (1-3) or workflow name, or ask a question like:
+- "I have a ticket to implement - what should I do?"
+- "How do I pause work and resume later?"
+- "What's the complete development workflow?"
+```
+
+Then wait for user input.
+
+## Processing User Input
+
+### Step 1: Detect Context
+
+Check if the user is already in a workflow by spawning parallel detection tasks:
+
+**Task 1 - Check for Active Work**:
+
+```
+Use codebase-locator agent:
+"Search for recent uncommitted changes, work-in-progress files, or partial implementations. Look for:
+- Git status (uncommitted files)
+- WIP branches
+- Partial plan files with unchecked boxes
+- Draft handoffs
+Return: Evidence of active work with file paths"
+
+Tools: Bash (git status), Grep, Glob
+```
+
+**Task 2 - Find Recent Documents**:
+
+```
+Use thoughts-locator agent (or Glob if no thoughts):
+"Find the most recent research, plan, or handoff documents. Look in:
+- thoughts/shared/research/ (or research/)
+- thoughts/shared/plans/ (or plans/)
+- thoughts/shared/handoffs/ (or handoffs/)
+Return: 3 most recent documents with dates and topics"
+
+Tools: Bash (ls -t), Grep, Glob
+```
+
+**Task 3 - Detect Worktree**:
+
+```
+"Check if currently in a git worktree (not main repo).
+Run: pwd and git worktree list
+Return: Whether in worktree, worktree name if applicable"
+
+Tools: Bash
+```
+
+WAIT for all tasks to complete.
+
+### Step 2: Analyze Context
+
+Based on detection results, determine user's current state:
+
+- **In Worktree with Plan** → Likely in Implementation phase
+- **Recent Research Doc** → May be ready for Planning
+- **Recent Plan Doc** → May be ready for Implementation
+- **Recent Handoff** → May want to resume
+- **No Active Work** → Starting fresh
+
+### Step 3: Provide Context-Aware Guidance
+
+**If User is in Active Workflow:**
+
+```
+🎯 **I see you're currently working on {detected-context}**
+
+**Current State:**
+- {What I detected - be specific with file paths}
+- {Where you likely are in workflow}
+
+**Suggested Next Steps:**
+1. {Most likely next action}
+2. {Alternative action}
+3. {How to pause/handoff if needed}
+
+**Context Management:**
+⚠️ Remember to CLEAR CONTEXT between workflow phases!
+- Current phase: {detected-phase}
+- Clear context after: {when to clear}
+
+**Note**: I can monitor my own context usage and will proactively warn you if it gets high. You can also check anytime with `/context`.
+
+Would you like me to:
+1. Continue with next step
+2. Explain the complete workflow
+3. Help you pause/create handoff
+4. Something else
+```
+
+**If User is Starting Fresh:**
+
+Proceed to workflow selection (Step 4).
+
+### Step 4: Workflow Selection
+
+Based on user's choice, spawn parallel research to provide comprehensive guidance:
+
+#### For Development Workflow (Option 1):
+
+Spawn 3 parallel research tasks:
+
+**Task 1 - Read Workflow Guide**:
+
+```
+"Read docs/AGENTIC_WORKFLOW_GUIDE.md and extract:
+- Complete workflow phases
+- Context clearing guidelines
+- When to use each command
+Return: Concise summary of complete workflow"
+
+Tools: Read
+```
+
+**Task 2 - Find Command Examples**:
+
+```
+"Search for examples in:
+- commands/research_codebase.md
+- commands/create_plan.md
+- commands/implement_plan.md
+Extract example usage and common patterns
+Return: Concrete examples users can follow"
+
+Tools: Read, Grep
+```
+
+**Task 3 - Check for User Files**:
+
+```
+"Check if user has any existing research, plans, or handoffs.
+Look in thoughts/ or research/, plans/, handoffs/ directories.
+Return: What files exist, suggesting next steps based on what's there"
+
+Tools: Glob, Bash
+```
+
+WAIT for all tasks.
+
+**Present Comprehensive Guide:**
+
+```
+# 🔄 Development Workflow: Research → Plan → Implement → Validate → PR
+
+{Synthesize findings from 3 parallel tasks}
+
+## Complete Process
+
+### Phase 1: Research 🔍
+**When**: Need to understand existing codebase before planning
+**Command**: `/research-codebase`
+
+{Include example from Task 2}
+{Note any existing research docs from Task 3}
+
+**Output**: `thoughts/shared/research/YYYY-MM-DD-PROJ-XXXX-description.md`
+**After**: ✅ **CLEAR CONTEXT**
+
+---
+
+### Phase 2: Planning 📋
+**When**: Ready to create implementation plan
+**Command**: `/create-plan`
+
+{Include example}
+
+**Output**: `thoughts/shared/plans/YYYY-MM-DD-PROJ-XXXX-description.md`
+**After**: ✅ **CLEAR CONTEXT**
+
+---
+
+### Phase 3: Worktree Creation 🌲
+**When**: Plan approved, ready to implement
+**How**:
+
+\`\`\`bash
+"${CLAUDE_PLUGIN_ROOT}/scripts/create-worktree.sh" PROJ-123 feature-name
+cd ~/wt/{project}/PROJ-123-feature
+\`\`\`
+
+**After**: ✅ **CLEAR CONTEXT** (fresh session in worktree)
+
+---
+
+### Phase 4: Implementation ⚙️
+**When**: In worktree with approved plan
+**Command**: `/implement-plan thoughts/shared/plans/YYYY-MM-DD-PROJ-XXXX-feature.md`
+
+{Include example}
+
+**Checkpoints**: After EACH phase in plan
+**After**: ✅ **CLEAR CONTEXT**
+
+---
+
+### Phase 5: Validation ✅
+**When**: All implementation phases complete
+**Command**: `/validate-plan`
+
+**After**: ✅ **CLEAR CONTEXT**
+
+---
+
+### Phase 6: PR Creation 🚀
+**Commands**:
+\`\`\`bash
+/catalyst-dev:commit
+gh pr create --fill
+/describe-pr
+\`\`\`
+
+**Output**: `thoughts/shared/prs/pr_{number}_{description}.md`
+**After**: ✅ **CLEAR CONTEXT** - workflow complete!
+
+---
+
+## 🔄 Handoff System (Pause/Resume)
+
+**Create Handoff** (to pause work):
+\`\`\`bash
+/create-handoff
+\`\`\`
+**Output**: `thoughts/shared/handoffs/PROJ-XXXX/YYYY-MM-DD_HH-MM-SS_description.md`
+
+**Resume Handoff**:
+\`\`\`bash
+/resume-handoff {path-or-ticket}
+\`\`\`
+
+---
+
+## ⚠️ Context Management
+
+**CLEAR CONTEXT between EVERY phase**
+- After research document created
+- After plan approved
+- After creating handoff
+- Before implementation in worktree
+- After implementation complete
+- Before validation
+- After PR created
+
+**Why?** Keeps AI performance optimal (40-60% context utilization)
+
+**How to check**: I monitor my context automatically and will warn you.
+You can also check anytime with `/context` command.
+
+**When I warn you**:
+- I'll show current usage: e.g., "65% (130K/200K tokens)"
+- I'll explain why clearing helps
+- I'll offer to create a handoff if needed
+- I'll tell you exactly what to do next
+
+**Context clearing is NORMAL and EXPECTED** - it's how we maintain quality!
+
+---
+
+{Based on Task 3 - suggest next step}
+
+**Your Next Step:**
+{If existing files found:} You have {file} - ready to {next-action}?
+{If no files:} Start with: `/research-codebase` or `/create-plan`
+
+**Need more details on any phase?** Just ask!
+```
+
+#### For Workflow Discovery (Option 2):
+
+Spawn parallel research:
+
+**Task 1**: Read `docs/WORKFLOW_DISCOVERY_SYSTEM.md` **Task 2**: Read command files
+(discover_workflows, import_workflow, etc.) **Task 3**: Check if user has any workflow catalog
+
+WAIT and synthesize similar to above.
+
+#### For Utilities (Option 3):
+
+Read relevant command files and provide quick reference.
+
+### Step 5: Answer Follow-Up Questions
+
+**If user asks specific questions:**
+
+Spawn focused research tasks to answer:
+
+**Example**: "How do I pause work and resume later?"
+
+```
+Task 1: "Read docs/AGENTIC_WORKFLOW_GUIDE.md section on Handoff System"
+Task 2: "Find examples in commands/create_handoff.md and commands/resume_handoff.md"
+Task 3: "Check if user has existing handoffs"
+```
+
+Present targeted answer with examples.
+
+### Step 6: Provide Quick Actions
+
+**Always end with actionable next steps:**
+
+```
+---
+
+## Ready to Get Started?
+
+**Quick Actions:**
+1. 📝 Start research: `/research-codebase`
+2. 📋 Create plan: `/create-plan`
+3. 🔄 Resume work: `/resume-handoff {ticket}`
+4. 🔍 Discover workflows: `/discover-workflows`
+5. ❓ Ask me anything else!
+
+**Pro Tips:**
+- Clear context between phases for best performance
+- Read outputs completely before next phase
+- Use handoffs liberally - context is precious
+- Worktrees isolate your changes safely
+
+Type a command or ask another question!
+```
+
+## Important Guidelines
+
+### Context-Aware Assistance
+
+1. **Always detect current state first** using parallel agents
+2. **Don't assume** - verify with actual file checks
+3. **Be specific** with file paths and next actions
+4. **Remind about context clearing** at appropriate points
+
+### Compression & Conciseness
+
+1. **Parallel agents research details** - keep main context clean
+2. **Synthesize findings** - don't dump raw agent outputs
+3. **Provide examples** - concrete > abstract
+4. **Quick reference** - users can dive deeper if needed
+
+### Link to Documentation
+
+**Always provide links** to detailed documentation:
+
+- Full workflow: `docs/AGENTIC_WORKFLOW_GUIDE.md`
+- Workflow discovery: `docs/WORKFLOW_DISCOVERY_SYSTEM.md`
+- Frontmatter: `docs/FRONTMATTER_STANDARD.md`
+- Main README: `README.md`
+
+### Web Research (If Needed)
+
+If user asks about external concepts:
+
+**Use external-research agent**:
+
+```
+"Research {topic} from HumanLayer or Anthropic documentation.
+Return: Summary with links to sources"
+
+Tools: WebSearch, WebFetch, mcp__deepwiki__ask_question
+```
+
+Include links in response.
+
+## Example Interactions
+
+### Example 1: User in Middle of Workflow
+
+```
+User: /workflow-help
+
+[Agent spawns 3 parallel detection tasks]
+
+Agent: 🎯 **I see you're currently working on PROJ-123 OAuth implementation**
+
+**Current State:**
+- Worktree: `~/wt/my-project/PROJ-123-oauth`
+- Plan: `thoughts/shared/plans/2025-01-08-PROJ-123-oauth.md`
+- Status: Phase 2/4 complete (checkboxes updated)
+
+**You're in Implementation Phase**
+
+**Suggested Next Steps:**
+1. ✅ Continue implementing Phase 3: `/implement-plan` (will resume from checkboxes)
+2. 🔄 Need to pause? `/create-handoff` before stopping
+3. 📖 Review plan: Check `thoughts/shared/plans/2025-01-08-PROJ-123-oauth.md`
+
+**Context Management:**
+⚠️ If context feels full (>60%), clear and resume with plan file
+
+Would you like me to:
+1. Continue with Phase 3
+2. Show complete workflow overview
+3. Help create handoff to pause work
+```
+
+### Example 2: User Starting Fresh
+
+```
+User: I have a ticket to implement OAuth support
+
+[Agent spawns detection tasks - finds no active work]
+
+Agent: 🎯 **Great! Let's start the Development Workflow for OAuth support**
+
+I don't see any existing research or plans for this, so let's start from the beginning.
+
+## Recommended Approach
+
+### Step 1: Research Phase 🔍
+First, understand how authentication currently works:
+
+\`\`\`
+/research-codebase
+\`\`\`
+
+When prompted, ask: "How does authentication currently work? What patterns exist?"
+
+**Output**: `thoughts/shared/research/YYYY-MM-DD-PROJ-XXX-auth-system.md`
+
+**After research**: ✅ **CLEAR CONTEXT** (close this conversation, start fresh)
+
+---
+
+### Step 2: Planning Phase 📋
+Create implementation plan:
+
+\`\`\`
+/create-plan
+\`\`\`
+
+Reference your research doc when planning.
+
+**Output**: `thoughts/shared/plans/YYYY-MM-DD-PROJ-XXX-oauth-support.md`
+
+**After plan approved**: ✅ **CLEAR CONTEXT**
+
+---
+
+{Continue with remaining phases...}
+
+**Ready to start research?** Type `/research-codebase` or ask more questions!
+```
+
+### Example 3: Quick Question
+
+```
+User: How do I pause work and resume later?
+
+[Agent reads handoff documentation]
+
+Agent: 🔄 **Pausing and Resuming Work**
+
+Use the **Handoff System** to pause/resume:
+
+### To Pause:
+\`\`\`bash
+/create-handoff
+\`\`\`
+
+Creates: `thoughts/shared/handoffs/PROJ-XXXX/YYYY-MM-DD_HH-MM-SS_description.md`
+
+The handoff captures:
+- Current progress
+- Critical file references
+- Next action items
+- Blockers/questions
+
+**After creating handoff**: ✅ **CLEAR CONTEXT** - you can safely stop
+
+---
+
+### To Resume:
+\`\`\`bash
+/resume-handoff thoughts/shared/handoffs/PROJ-123/2025-01-08_14-30-45_oauth.md
+\`\`\`
+
+Or if command supports:
+\`\`\`bash
+/resume-handoff PROJ-123  # Finds latest handoff
+\`\`\`
+
+**The resume process:**
+1. Reads handoff + linked docs
+2. Verifies current state
+3. Proposes next actions
+4. Continues where you left off
+
+---
+
+**Pro Tip**: Create handoffs liberally! Any time:
+- End of day
+- Context fills up (>60%)
+- Need to switch tasks
+- Blocked and need input
+
+See full guide: `docs/AGENTIC_WORKFLOW_GUIDE.md` (Handoff System section)
+
+**Anything else?**
+```
+
+## Advanced Features
+
+### Workflow State Detection
+
+The parallel agents can detect:
+
+- Current git branch
+- Worktree vs main repo
+- Recent files modified
+- Plan files with checkboxes
+- Research documents
+- Handoff documents
+- PR status
+
+### Personalized Guidance
+
+Based on detected state, provide:
+
+- Specific file paths to reference
+- Exact commands to run next
+- Progress indicators (Phase X of Y)
+- Context clearing reminders at right moments
+
+### Link to External Resources
+
+When relevant, include links:
+
+```
+**Further Reading:**
+- [HumanLayer Advanced Context Engineering](https://github.com/humanlayer/advanced-context-engineering-for-coding-agents)
+- [12 Factor Agents](https://github.com/humanlayer/12-factor-agents)
+- [Anthropic Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)
+```
+
+## Important Notes
+
+- **Use parallel agents** to research docs - keeps main context clean
+- **Be context-aware** - detect where user is in workflow
+- **Provide concrete examples** - not just theory
+- **Remind about context clearing** - critical for performance
+- **Link to detailed docs** - comprehensive info available
+- **Quick actionable steps** - users can start immediately
+- **Follow-up friendly** - can answer deeper questions
+
+This command serves as an interactive, intelligent guide to the entire workflow system!
diff --git a/plugin.lock.json b/plugin.lock.json
new file mode 100644
index 0000000..3f88bf4
--- /dev/null
+++ b/plugin.lock.json
@@ -0,0 +1,61 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:coalesce-labs/catalyst:plugins/meta",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "f38839daa73569543f44e9804a498cfe04c6c736",
+    "treeHash": "a56be0e5748dd5099830e9a9cfb5a24529c9881f08c5043f8fd297df62dedb62",
+    "generatedAt": "2025-11-28T10:15:42.126467Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "catalyst-meta",
+    "description": "Workflow discovery and creation tools: learn from community patterns and extend Catalyst with new workflows.",
+    "version": "2.0.1"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "390911f1808aa9ead5abe8ec18a667d35042d086b73cf5c251f2c02eb706a657"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "24e1a19178e48450876eacaafc2d1e4fab894baf4c7762578fa92665e94aa38a"
+      },
+      {
+        "path": "commands/create_workflow.md",
+        "sha256": "4b3f4b0b7021973949274a82802f0a2dc18331a4fddfc8c7a8ba2c33e3b86598"
+      },
+      {
+        "path": "commands/validate_frontmatter.md",
+        "sha256": "7f2ee7b09c10deb8fcd469d09ccb92a5564f3b446acbfac4f26fbcb1b5cdafde"
+      },
+      {
+        "path": "commands/workflow_help.md",
+        "sha256": "6a7de42664c6ba6595f1e3fdc6b6f160a88c50b4391398739cfad86d5346ce61"
+      },
+      {
+        "path": "commands/import_workflow.md",
+        "sha256": "9ce593b4449997fe4be2db56faadfd2294419dd319f1abce8690caea4bb7c500"
+      },
+      {
+        "path": "commands/discover_workflows.md",
+        "sha256": "63778c1227ad679ec66d1e865ab20b2abc4c9e233aa81557a2ec7e5877b75f81"
+      }
+    ],
+    "dirSha256": "a56be0e5748dd5099830e9a9cfb5a24529c9881f08c5043f8fd297df62dedb62"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
\ No newline at end of file