Initial commit
This commit is contained in:
Zhongwei Li
13
.claude-plugin/plugin.json
Normal file
13
.claude-plugin/plugin.json
Normal file
@@ -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"
|
||||||
|
]
|
||||||
|
}
|
||||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
|||||||
|
# catalyst-meta
|
||||||
|
|
||||||
|
Workflow discovery and creation tools: learn from community patterns and extend Catalyst with new workflows.
|
||||||
617
commands/create_workflow.md
Normal file
617
commands/create_workflow.md
Normal file
@@ -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!
|
||||||
367
commands/discover_workflows.md
Normal file
367
commands/discover_workflows.md
Normal file
@@ -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!
|
||||||
347
commands/import_workflow.md
Normal file
347
commands/import_workflow.md
Normal file
@@ -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!
|
||||||
666
commands/validate_frontmatter.md
Normal file
666
commands/validate_frontmatter.md
Normal file
@@ -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!
|
||||||
|
```
|
||||||
592
commands/workflow_help.md
Normal file
592
commands/workflow_help.md
Normal file
@@ -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!
|
||||||
61
plugin.lock.json
Normal file
61
plugin.lock.json
Normal file
@@ -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": []
|
||||||
|
}
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user