zhongwei/gh-coalesce-labs-catalyst-plugins-meta
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:14:41 +08:00
commit 1589849890
8 changed files with 2666 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

617
commands/create_workflow.md Normal file
View 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
View 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
View 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
View 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
View 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!