Initial commit
This commit is contained in:
Zhongwei Li
722
skills/command-development/references/advanced-workflows.md
Normal file
722
skills/command-development/references/advanced-workflows.md
Normal file
@@ -0,0 +1,722 @@
|
||||
# Advanced Workflow Patterns
|
||||
|
||||
Multi-step command sequences and composition patterns for complex workflows.
|
||||
|
||||
## Overview
|
||||
|
||||
Advanced workflows combine multiple commands, coordinate state across invocations, and create sophisticated automation sequences. These patterns enable building complex functionality from simple command building blocks.
|
||||
|
||||
## Multi-Step Command Patterns
|
||||
|
||||
### Sequential Workflow Command
|
||||
|
||||
Commands that guide users through multi-step processes:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Complete PR review workflow
|
||||
argument-hint: [pr-number]
|
||||
allowed-tools: Bash(gh:*), Read, Grep
|
||||
---
|
||||
|
||||
# PR Review Workflow for #$1
|
||||
|
||||
## Step 1: Fetch PR Details
|
||||
!`gh pr view $1 --json title,body,author,files`
|
||||
|
||||
## Step 2: Review Files
|
||||
Files changed: !`gh pr diff $1 --name-only`
|
||||
|
||||
For each file:
|
||||
- Check code quality
|
||||
- Verify tests exist
|
||||
- Review documentation
|
||||
|
||||
## Step 3: Run Checks
|
||||
Test status: !`gh pr checks $1`
|
||||
|
||||
Verify:
|
||||
- All tests passing
|
||||
- No merge conflicts
|
||||
- CI/CD successful
|
||||
|
||||
## Step 4: Provide Feedback
|
||||
|
||||
Summarize:
|
||||
- Issues found (critical/minor)
|
||||
- Suggestions for improvement
|
||||
- Approval recommendation
|
||||
|
||||
Would you like to:
|
||||
1. Approve PR
|
||||
2. Request changes
|
||||
3. Leave comments only
|
||||
|
||||
Reply with your choice and I'll help complete the action.
|
||||
```
|
||||
|
||||
**Key features:**
|
||||
- Numbered steps for clarity
|
||||
- Bash execution for context
|
||||
- Decision points for user input
|
||||
- Next action suggestions
|
||||
|
||||
### State-Carrying Workflow
|
||||
|
||||
Commands that maintain state between invocations:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Initialize deployment workflow
|
||||
allowed-tools: Write, Bash(git:*)
|
||||
---
|
||||
|
||||
# Initialize Deployment
|
||||
|
||||
Creating deployment tracking file...
|
||||
|
||||
Current branch: !`git branch --show-current`
|
||||
Latest commit: !`git log -1 --format=%H`
|
||||
|
||||
Deployment state saved to `.claude/deployment-state.local.md`:
|
||||
|
||||
\`\`\`markdown
|
||||
---
|
||||
initialized: true
|
||||
branch: $(git branch --show-current)
|
||||
commit: $(git log -1 --format=%H)
|
||||
timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)
|
||||
status: initialized
|
||||
---
|
||||
|
||||
# Deployment Tracking
|
||||
|
||||
Branch: $(git branch --show-current)
|
||||
Started: $(date)
|
||||
|
||||
Next steps:
|
||||
1. Run tests: /deploy-test
|
||||
2. Build: /deploy-build
|
||||
3. Deploy: /deploy-execute
|
||||
\`\`\`
|
||||
|
||||
State saved. Run `/deploy-test` to continue.
|
||||
```
|
||||
|
||||
**Next command** (`/deploy-test`):
|
||||
```markdown
|
||||
---
|
||||
description: Run deployment tests
|
||||
allowed-tools: Read, Bash(npm:*)
|
||||
---
|
||||
|
||||
Reading deployment state from `.claude/deployment-state.local.md`...
|
||||
|
||||
Running tests: !`npm test`
|
||||
|
||||
Updating state to 'tested'...
|
||||
|
||||
Tests complete. Run `/deploy-build` to continue.
|
||||
```
|
||||
|
||||
**Pattern benefits:**
|
||||
- Persistent state across commands
|
||||
- Clear workflow progression
|
||||
- Safety checkpoints
|
||||
- Resume capability
|
||||
|
||||
### Conditional Workflow Branching
|
||||
|
||||
Commands that adapt based on conditions:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Smart deployment workflow
|
||||
argument-hint: [environment]
|
||||
allowed-tools: Bash(git:*), Bash(npm:*), Read
|
||||
---
|
||||
|
||||
# Deploy to $1
|
||||
|
||||
## Pre-flight Checks
|
||||
|
||||
Branch: !`git branch --show-current`
|
||||
Status: !`git status --short`
|
||||
|
||||
**Checking conditions:**
|
||||
|
||||
1. Branch status:
|
||||
- If main/master: Require approval
|
||||
- If feature branch: Warning about target
|
||||
- If hotfix: Fast-track process
|
||||
|
||||
2. Tests:
|
||||
!`npm test`
|
||||
- If tests fail: STOP - fix tests first
|
||||
- If tests pass: Continue
|
||||
|
||||
3. Environment:
|
||||
- If $1 = 'production': Extra validation
|
||||
- If $1 = 'staging': Standard process
|
||||
- If $1 = 'dev': Minimal checks
|
||||
|
||||
**Workflow decision:**
|
||||
Based on above, proceeding with: [determined workflow]
|
||||
|
||||
[Conditional steps based on environment and status]
|
||||
|
||||
Ready to deploy? (yes/no)
|
||||
```
|
||||
|
||||
## Command Composition Patterns
|
||||
|
||||
### Command Chaining
|
||||
|
||||
Commands designed to work together:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Prepare for code review
|
||||
---
|
||||
|
||||
# Prepare Code Review
|
||||
|
||||
Running preparation sequence:
|
||||
|
||||
1. Format code: /format-code
|
||||
2. Run linter: /lint-code
|
||||
3. Run tests: /test-all
|
||||
4. Generate coverage: /coverage-report
|
||||
5. Create review summary: /review-summary
|
||||
|
||||
This is a meta-command. After completing each step above,
|
||||
I'll compile results and prepare comprehensive review materials.
|
||||
|
||||
Starting sequence...
|
||||
```
|
||||
|
||||
**Individual commands** are simple:
|
||||
- `/format-code` - Just formats
|
||||
- `/lint-code` - Just lints
|
||||
- `/test-all` - Just tests
|
||||
|
||||
**Composition command** orchestrates them.
|
||||
|
||||
### Pipeline Pattern
|
||||
|
||||
Commands that process output from previous commands:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Analyze test failures
|
||||
---
|
||||
|
||||
# Analyze Test Failures
|
||||
|
||||
## Step 1: Get test results
|
||||
(Run /test-all first if not done)
|
||||
|
||||
Reading test output...
|
||||
|
||||
## Step 2: Categorize failures
|
||||
- Flaky tests (random failures)
|
||||
- Consistent failures
|
||||
- New failures vs existing
|
||||
|
||||
## Step 3: Prioritize
|
||||
Rank by:
|
||||
- Impact (critical path vs edge case)
|
||||
- Frequency (always fails vs sometimes)
|
||||
- Effort (quick fix vs major work)
|
||||
|
||||
## Step 4: Generate fix plan
|
||||
For each failure:
|
||||
- Root cause hypothesis
|
||||
- Suggested fix approach
|
||||
- Estimated effort
|
||||
|
||||
Would you like me to:
|
||||
1. Fix highest priority failure
|
||||
2. Generate detailed fix plans for all
|
||||
3. Create GitHub issues for each
|
||||
```
|
||||
|
||||
### Parallel Execution Pattern
|
||||
|
||||
Commands that coordinate multiple simultaneous operations:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Run comprehensive validation
|
||||
allowed-tools: Bash(*), Read
|
||||
---
|
||||
|
||||
# Comprehensive Validation
|
||||
|
||||
Running validations in parallel...
|
||||
|
||||
Starting:
|
||||
- Code quality checks
|
||||
- Security scanning
|
||||
- Dependency audit
|
||||
- Performance profiling
|
||||
|
||||
This will take 2-3 minutes. I'll monitor all processes
|
||||
and report when complete.
|
||||
|
||||
[Poll each process and report progress]
|
||||
|
||||
All validations complete. Summary:
|
||||
- Quality: PASS (0 issues)
|
||||
- Security: WARN (2 minor issues)
|
||||
- Dependencies: PASS
|
||||
- Performance: PASS (baseline met)
|
||||
|
||||
Details:
|
||||
[Collated results from all checks]
|
||||
```
|
||||
|
||||
## Workflow State Management
|
||||
|
||||
### Using .local.md Files
|
||||
|
||||
Store workflow state in plugin-specific files:
|
||||
|
||||
```markdown
|
||||
.claude/plugin-name-workflow.local.md:
|
||||
|
||||
---
|
||||
workflow: deployment
|
||||
stage: testing
|
||||
started: 2025-01-15T10:30:00Z
|
||||
environment: staging
|
||||
branch: feature/new-api
|
||||
commit: abc123def
|
||||
tests_passed: false
|
||||
build_complete: false
|
||||
---
|
||||
|
||||
# Deployment Workflow State
|
||||
|
||||
Current stage: Testing
|
||||
Started: 2025-01-15 10:30 UTC
|
||||
|
||||
Completed steps:
|
||||
- ✅ Validation
|
||||
- ✅ Branch check
|
||||
- ⏳ Testing (in progress)
|
||||
|
||||
Pending steps:
|
||||
- Build
|
||||
- Deploy
|
||||
- Smoke tests
|
||||
```
|
||||
|
||||
**Reading state in commands:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Continue deployment workflow
|
||||
allowed-tools: Read, Write
|
||||
---
|
||||
|
||||
Reading workflow state from .claude/plugin-name-workflow.local.md...
|
||||
|
||||
Current stage: @.claude/plugin-name-workflow.local.md
|
||||
|
||||
[Parse YAML frontmatter to determine next step]
|
||||
|
||||
Next action based on state: [determined action]
|
||||
```
|
||||
|
||||
### Workflow Recovery
|
||||
|
||||
Handle interrupted workflows:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Resume deployment workflow
|
||||
allowed-tools: Read
|
||||
---
|
||||
|
||||
# Resume Deployment
|
||||
|
||||
Checking for interrupted workflow...
|
||||
|
||||
State file: @.claude/plugin-name-workflow.local.md
|
||||
|
||||
**Workflow found:**
|
||||
- Started: [timestamp]
|
||||
- Environment: [env]
|
||||
- Last completed: [step]
|
||||
|
||||
**Recovery options:**
|
||||
1. Resume from last step
|
||||
2. Restart from beginning
|
||||
3. Abort and clean up
|
||||
|
||||
Which would you like? (1/2/3)
|
||||
```
|
||||
|
||||
## Workflow Coordination Patterns
|
||||
|
||||
### Cross-Command Communication
|
||||
|
||||
Commands that signal each other:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Mark feature complete
|
||||
allowed-tools: Write
|
||||
---
|
||||
|
||||
# Mark Feature Complete
|
||||
|
||||
Writing completion marker...
|
||||
|
||||
Creating: .claude/feature-complete.flag
|
||||
|
||||
This signals other commands that feature is ready for:
|
||||
- Integration testing (/integration-test will auto-detect)
|
||||
- Documentation generation (/docs-generate will include)
|
||||
- Release notes (/release-notes will add)
|
||||
|
||||
Feature marked complete.
|
||||
```
|
||||
|
||||
**Other commands check for flag:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Generate release notes
|
||||
allowed-tools: Read, Bash(git:*)
|
||||
---
|
||||
|
||||
Checking for completed features...
|
||||
|
||||
if [ -f .claude/feature-complete.flag ]; then
|
||||
Feature ready for release notes
|
||||
fi
|
||||
|
||||
[Include in release notes]
|
||||
```
|
||||
|
||||
### Workflow Locking
|
||||
|
||||
Prevent concurrent workflow execution:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Start deployment
|
||||
allowed-tools: Read, Write, Bash
|
||||
---
|
||||
|
||||
# Start Deployment
|
||||
|
||||
Checking for active deployments...
|
||||
|
||||
if [ -f .claude/deployment.lock ]; then
|
||||
ERROR: Deployment already in progress
|
||||
Started: [timestamp from lock file]
|
||||
|
||||
Cannot start concurrent deployment.
|
||||
Wait for completion or run /deployment-abort
|
||||
|
||||
Exit.
|
||||
fi
|
||||
|
||||
Creating deployment lock...
|
||||
|
||||
Deployment started. Lock created.
|
||||
[Proceed with deployment]
|
||||
```
|
||||
|
||||
**Lock cleanup:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Complete deployment
|
||||
allowed-tools: Write, Bash
|
||||
---
|
||||
|
||||
Deployment complete.
|
||||
|
||||
Removing deployment lock...
|
||||
rm .claude/deployment.lock
|
||||
|
||||
Ready for next deployment.
|
||||
```
|
||||
|
||||
## Advanced Argument Handling
|
||||
|
||||
### Optional Arguments with Defaults
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Deploy with optional version
|
||||
argument-hint: [environment] [version]
|
||||
---
|
||||
|
||||
Environment: ${1:-staging}
|
||||
Version: ${2:-latest}
|
||||
|
||||
Deploying ${2:-latest} to ${1:-staging}...
|
||||
|
||||
Note: Using defaults for missing arguments:
|
||||
- Environment defaults to 'staging'
|
||||
- Version defaults to 'latest'
|
||||
```
|
||||
|
||||
### Argument Validation
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Deploy to validated environment
|
||||
argument-hint: [environment]
|
||||
---
|
||||
|
||||
Environment: $1
|
||||
|
||||
Validating environment...
|
||||
|
||||
valid_envs="dev staging production"
|
||||
if ! echo "$valid_envs" | grep -w "$1" > /dev/null; then
|
||||
ERROR: Invalid environment '$1'
|
||||
Valid options: dev, staging, production
|
||||
Exit.
|
||||
fi
|
||||
|
||||
Environment validated. Proceeding...
|
||||
```
|
||||
|
||||
### Argument Transformation
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Deploy with shorthand
|
||||
argument-hint: [env-shorthand]
|
||||
---
|
||||
|
||||
Input: $1
|
||||
|
||||
Expanding shorthand:
|
||||
- d/dev → development
|
||||
- s/stg → staging
|
||||
- p/prod → production
|
||||
|
||||
case "$1" in
|
||||
d|dev) ENV="development";;
|
||||
s|stg) ENV="staging";;
|
||||
p|prod) ENV="production";;
|
||||
*) ENV="$1";;
|
||||
esac
|
||||
|
||||
Deploying to: $ENV
|
||||
```
|
||||
|
||||
## Error Handling in Workflows
|
||||
|
||||
### Graceful Failure
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Resilient deployment workflow
|
||||
---
|
||||
|
||||
# Deployment Workflow
|
||||
|
||||
Running steps with error handling...
|
||||
|
||||
## Step 1: Tests
|
||||
!`npm test`
|
||||
|
||||
if [ $? -ne 0 ]; then
|
||||
ERROR: Tests failed
|
||||
|
||||
Options:
|
||||
1. Fix tests and retry
|
||||
2. Skip tests (NOT recommended)
|
||||
3. Abort deployment
|
||||
|
||||
What would you like to do?
|
||||
|
||||
[Wait for user input before continuing]
|
||||
fi
|
||||
|
||||
## Step 2: Build
|
||||
[Continue only if Step 1 succeeded]
|
||||
```
|
||||
|
||||
### Rollback on Failure
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Deployment with rollback
|
||||
---
|
||||
|
||||
# Deploy with Rollback
|
||||
|
||||
Saving current state for rollback...
|
||||
Previous version: !`current-version.sh`
|
||||
|
||||
Deploying new version...
|
||||
|
||||
!`deploy.sh`
|
||||
|
||||
if [ $? -ne 0 ]; then
|
||||
DEPLOYMENT FAILED
|
||||
|
||||
Initiating automatic rollback...
|
||||
!`rollback.sh`
|
||||
|
||||
Rolled back to previous version.
|
||||
Check logs for failure details.
|
||||
fi
|
||||
|
||||
Deployment complete.
|
||||
```
|
||||
|
||||
### Checkpoint Recovery
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Workflow with checkpoints
|
||||
---
|
||||
|
||||
# Multi-Stage Deployment
|
||||
|
||||
## Checkpoint 1: Validation
|
||||
!`validate.sh`
|
||||
echo "checkpoint:validation" >> .claude/deployment-checkpoints.log
|
||||
|
||||
## Checkpoint 2: Build
|
||||
!`build.sh`
|
||||
echo "checkpoint:build" >> .claude/deployment-checkpoints.log
|
||||
|
||||
## Checkpoint 3: Deploy
|
||||
!`deploy.sh`
|
||||
echo "checkpoint:deploy" >> .claude/deployment-checkpoints.log
|
||||
|
||||
If any step fails, resume with:
|
||||
/deployment-resume [last-successful-checkpoint]
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Workflow Design
|
||||
|
||||
1. **Clear progression**: Number steps, show current position
|
||||
2. **Explicit state**: Don't rely on implicit state
|
||||
3. **User control**: Provide decision points
|
||||
4. **Error recovery**: Handle failures gracefully
|
||||
5. **Progress indication**: Show what's done, what's pending
|
||||
|
||||
### Command Composition
|
||||
|
||||
1. **Single responsibility**: Each command does one thing well
|
||||
2. **Composable design**: Commands work together easily
|
||||
3. **Standard interfaces**: Consistent input/output formats
|
||||
4. **Loose coupling**: Commands don't depend on each other's internals
|
||||
|
||||
### State Management
|
||||
|
||||
1. **Persistent state**: Use .local.md files
|
||||
2. **Atomic updates**: Write complete state files atomically
|
||||
3. **State validation**: Check state file format/completeness
|
||||
4. **Cleanup**: Remove stale state files
|
||||
5. **Documentation**: Document state file formats
|
||||
|
||||
### Error Handling
|
||||
|
||||
1. **Fail fast**: Detect errors early
|
||||
2. **Clear messages**: Explain what went wrong
|
||||
3. **Recovery options**: Provide clear next steps
|
||||
4. **State preservation**: Keep state for recovery
|
||||
5. **Rollback capability**: Support undoing changes
|
||||
|
||||
## Example: Complete Deployment Workflow
|
||||
|
||||
### Initialize Command
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Initialize deployment
|
||||
argument-hint: [environment]
|
||||
allowed-tools: Write, Bash(git:*)
|
||||
---
|
||||
|
||||
# Initialize Deployment to $1
|
||||
|
||||
Creating workflow state...
|
||||
|
||||
\`\`\`yaml
|
||||
---
|
||||
workflow: deployment
|
||||
environment: $1
|
||||
branch: !`git branch --show-current`
|
||||
commit: !`git rev-parse HEAD`
|
||||
stage: initialized
|
||||
timestamp: !`date -u +%Y-%m-%dT%H:%M:%SZ`
|
||||
---
|
||||
\`\`\`
|
||||
|
||||
Written to .claude/deployment-state.local.md
|
||||
|
||||
Next: Run /deployment-validate
|
||||
```
|
||||
|
||||
### Validation Command
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Validate deployment
|
||||
allowed-tools: Read, Bash
|
||||
---
|
||||
|
||||
Reading state: @.claude/deployment-state.local.md
|
||||
|
||||
Running validation...
|
||||
- Branch check: PASS
|
||||
- Tests: PASS
|
||||
- Build: PASS
|
||||
|
||||
Updating state to 'validated'...
|
||||
|
||||
Next: Run /deployment-execute
|
||||
```
|
||||
|
||||
### Execution Command
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Execute deployment
|
||||
allowed-tools: Read, Bash, Write
|
||||
---
|
||||
|
||||
Reading state: @.claude/deployment-state.local.md
|
||||
|
||||
Executing deployment to [environment]...
|
||||
|
||||
!`deploy.sh [environment]`
|
||||
|
||||
Deployment complete.
|
||||
Updating state to 'completed'...
|
||||
|
||||
Cleanup: /deployment-cleanup
|
||||
```
|
||||
|
||||
### Cleanup Command
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: Clean up deployment
|
||||
allowed-tools: Bash
|
||||
---
|
||||
|
||||
Removing deployment state...
|
||||
rm .claude/deployment-state.local.md
|
||||
|
||||
Deployment workflow complete.
|
||||
```
|
||||
|
||||
This complete workflow demonstrates state management, sequential execution, error handling, and clean separation of concerns across multiple commands.
|
||||
Reference in New Issue
Block a user