surshar / claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

Built by Anthropic · github.com/anthropics

claude-code / plugins / plugin-dev / skills / command-development / references / advanced-workflows.md

Daisy S. HollmanMerge pull request #11780 from anthropics/daisy/plugin-dev/public-marketplace c508e59 · on Nov 18, 2025 History

722 lines · 13.3 KBPreview CodeRaw

1	# Advanced Workflow Patterns
2
3	Multi-step command sequences and composition patterns for complex workflows.
4
5	## Overview
6
7	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.
8
9	## Multi-Step Command Patterns
10
11	### Sequential Workflow Command
12
13	Commands that guide users through multi-step processes:
14
15	```markdown
16	---
17	description: Complete PR review workflow
18	argument-hint: [pr-number]
19	allowed-tools: Bash(gh:*), Read, Grep
20	---
21
22	# PR Review Workflow for #$1
23
24	## Step 1: Fetch PR Details
25	!`gh pr view $1 --json title,body,author,files`
26
27	## Step 2: Review Files
28	Files changed: !`gh pr diff $1 --name-only`
29
30	For each file:
31	- Check code quality
32	- Verify tests exist
33	- Review documentation
34
35	## Step 3: Run Checks
36	Test status: !`gh pr checks $1`
37
38	Verify:
39	- All tests passing
40	- No merge conflicts
41	- CI/CD successful
42
43	## Step 4: Provide Feedback
44
45	Summarize:
46	- Issues found (critical/minor)
47	- Suggestions for improvement
48	- Approval recommendation
49
50	Would you like to:
51	1. Approve PR
52	2. Request changes
53	3. Leave comments only
54
55	Reply with your choice and I'll help complete the action.
56	```
57
58	Key features:
59	- Numbered steps for clarity
60	- Bash execution for context
61	- Decision points for user input
62	- Next action suggestions
63
64	### State-Carrying Workflow
65
66	Commands that maintain state between invocations:
67
68	```markdown
69	---
70	description: Initialize deployment workflow
71	allowed-tools: Write, Bash(git:*)
72	---
73
74	# Initialize Deployment
75
76	Creating deployment tracking file...
77
78	Current branch: !`git branch --show-current`
79	Latest commit: !`git log -1 --format=%H`
80
81	Deployment state saved to `.claude/deployment-state.local.md`:
82
83	\`\`\`markdown
84	---
85	initialized: true
86	branch: $(git branch --show-current)
87	commit: $(git log -1 --format=%H)
88	timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)
89	status: initialized
90	---
91
92	# Deployment Tracking
93
94	Branch: $(git branch --show-current)
95	Started: $(date)
96
97	Next steps:
98	1. Run tests: /deploy-test
99	2. Build: /deploy-build
100	3. Deploy: /deploy-execute
101	\`\`\`
102
103	State saved. Run `/deploy-test` to continue.
104	```
105
106	Next command (`/deploy-test`):
107	```markdown
108	---
109	description: Run deployment tests
110	allowed-tools: Read, Bash(npm:*)
111	---
112
113	Reading deployment state from `.claude/deployment-state.local.md`...
114
115	Running tests: !`npm test`
116
117	Updating state to 'tested'...
118
119	Tests complete. Run `/deploy-build` to continue.
120	```
121
122	Pattern benefits:
123	- Persistent state across commands
124	- Clear workflow progression
125	- Safety checkpoints
126	- Resume capability
127
128	### Conditional Workflow Branching
129
130	Commands that adapt based on conditions:
131
132	```markdown
133	---
134	description: Smart deployment workflow
135	argument-hint: [environment]
136	allowed-tools: Bash(git:), Bash(npm:), Read
137	---
138
139	# Deploy to $1
140
141	## Pre-flight Checks
142
143	Branch: !`git branch --show-current`
144	Status: !`git status --short`
145
146	Checking conditions:
147
148	1. Branch status:
149	- If main/master: Require approval
150	- If feature branch: Warning about target
151	- If hotfix: Fast-track process
152
153	2. Tests:
154	!`npm test`
155	- If tests fail: STOP - fix tests first
156	- If tests pass: Continue
157
158	3. Environment:
159	- If $1 = 'production': Extra validation
160	- If $1 = 'staging': Standard process
161	- If $1 = 'dev': Minimal checks
162
163	Workflow decision:
164	Based on above, proceeding with: [determined workflow]
165
166	[Conditional steps based on environment and status]
167
168	Ready to deploy? (yes/no)
169	```
170
171	## Command Composition Patterns
172
173	### Command Chaining
174
175	Commands designed to work together:
176
177	```markdown
178	---
179	description: Prepare for code review
180	---
181
182	# Prepare Code Review
183
184	Running preparation sequence:
185
186	1. Format code: /format-code
187	2. Run linter: /lint-code
188	3. Run tests: /test-all
189	4. Generate coverage: /coverage-report
190	5. Create review summary: /review-summary
191
192	This is a meta-command. After completing each step above,
193	I'll compile results and prepare comprehensive review materials.
194
195	Starting sequence...
196	```
197
198	Individual commands are simple:
199	- `/format-code` - Just formats
200	- `/lint-code` - Just lints
201	- `/test-all` - Just tests
202
203	Composition command orchestrates them.
204
205	### Pipeline Pattern
206
207	Commands that process output from previous commands:
208
209	```markdown
210	---
211	description: Analyze test failures
212	---
213
214	# Analyze Test Failures
215
216	## Step 1: Get test results
217	(Run /test-all first if not done)
218
219	Reading test output...
220
221	## Step 2: Categorize failures
222	- Flaky tests (random failures)
223	- Consistent failures
224	- New failures vs existing
225
226	## Step 3: Prioritize
227	Rank by:
228	- Impact (critical path vs edge case)
229	- Frequency (always fails vs sometimes)
230	- Effort (quick fix vs major work)
231
232	## Step 4: Generate fix plan
233	For each failure:
234	- Root cause hypothesis
235	- Suggested fix approach
236	- Estimated effort
237
238	Would you like me to:
239	1. Fix highest priority failure
240	2. Generate detailed fix plans for all
241	3. Create GitHub issues for each
242	```
243
244	### Parallel Execution Pattern
245
246	Commands that coordinate multiple simultaneous operations:
247
248	```markdown
249	---
250	description: Run comprehensive validation
251	allowed-tools: Bash(*), Read
252	---
253
254	# Comprehensive Validation
255
256	Running validations in parallel...
257
258	Starting:
259	- Code quality checks
260	- Security scanning
261	- Dependency audit
262	- Performance profiling
263
264	This will take 2-3 minutes. I'll monitor all processes
265	and report when complete.
266
267	[Poll each process and report progress]
268
269	All validations complete. Summary:
270	- Quality: PASS (0 issues)
271	- Security: WARN (2 minor issues)
272	- Dependencies: PASS
273	- Performance: PASS (baseline met)
274
275	Details:
276	[Collated results from all checks]
277	```
278
279	## Workflow State Management
280
281	### Using .local.md Files
282
283	Store workflow state in plugin-specific files:
284
285	```markdown
286	.claude/plugin-name-workflow.local.md:
287
288	---
289	workflow: deployment
290	stage: testing
291	started: 2025-01-15T10:30:00Z
292	environment: staging
293	branch: feature/new-api
294	commit: abc123def
295	tests_passed: false
296	build_complete: false
297	---
298
299	# Deployment Workflow State
300
301	Current stage: Testing
302	Started: 2025-01-15 10:30 UTC
303
304	Completed steps:
305	- ✅ Validation
306	- ✅ Branch check
307	- ⏳ Testing (in progress)
308
309	Pending steps:
310	- Build
311	- Deploy
312	- Smoke tests
313	```
314
315	Reading state in commands:
316
317	```markdown
318	---
319	description: Continue deployment workflow
320	allowed-tools: Read, Write
321	---
322
323	Reading workflow state from .claude/plugin-name-workflow.local.md...
324
325	Current stage: @.claude/plugin-name-workflow.local.md
326
327	[Parse YAML frontmatter to determine next step]
328
329	Next action based on state: [determined action]
330	```
331
332	### Workflow Recovery
333
334	Handle interrupted workflows:
335
336	```markdown
337	---
338	description: Resume deployment workflow
339	allowed-tools: Read
340	---
341
342	# Resume Deployment
343
344	Checking for interrupted workflow...
345
346	State file: @.claude/plugin-name-workflow.local.md
347
348	Workflow found:
349	- Started: [timestamp]
350	- Environment: [env]
351	- Last completed: [step]
352
353	Recovery options:
354	1. Resume from last step
355	2. Restart from beginning
356	3. Abort and clean up
357
358	Which would you like? (1/2/3)
359	```
360
361	## Workflow Coordination Patterns
362
363	### Cross-Command Communication
364
365	Commands that signal each other:
366
367	```markdown
368	---
369	description: Mark feature complete
370	allowed-tools: Write
371	---
372
373	# Mark Feature Complete
374
375	Writing completion marker...
376
377	Creating: .claude/feature-complete.flag
378
379	This signals other commands that feature is ready for:
380	- Integration testing (/integration-test will auto-detect)
381	- Documentation generation (/docs-generate will include)
382	- Release notes (/release-notes will add)
383
384	Feature marked complete.
385	```
386
387	Other commands check for flag:
388
389	```markdown
390	---
391	description: Generate release notes
392	allowed-tools: Read, Bash(git:*)
393	---
394
395	Checking for completed features...
396
397	if [ -f .claude/feature-complete.flag ]; then
398	Feature ready for release notes
399	fi
400
401	[Include in release notes]
402	```
403
404	### Workflow Locking
405
406	Prevent concurrent workflow execution:
407
408	```markdown
409	---
410	description: Start deployment
411	allowed-tools: Read, Write, Bash
412	---
413
414	# Start Deployment
415
416	Checking for active deployments...
417
418	if [ -f .claude/deployment.lock ]; then
419	ERROR: Deployment already in progress
420	Started: [timestamp from lock file]
421
422	Cannot start concurrent deployment.
423	Wait for completion or run /deployment-abort
424
425	Exit.
426	fi
427
428	Creating deployment lock...
429
430	Deployment started. Lock created.
431	[Proceed with deployment]
432	```
433
434	Lock cleanup:
435
436	```markdown
437	---
438	description: Complete deployment
439	allowed-tools: Write, Bash
440	---
441
442	Deployment complete.
443
444	Removing deployment lock...
445	rm .claude/deployment.lock
446
447	Ready for next deployment.
448	```
449
450	## Advanced Argument Handling
451
452	### Optional Arguments with Defaults
453
454	```markdown
455	---
456	description: Deploy with optional version
457	argument-hint: [environment] [version]
458	---
459
460	Environment: ${1:-staging}
461	Version: ${2:-latest}
462
463	Deploying ${2:-latest} to ${1:-staging}...
464
465	Note: Using defaults for missing arguments:
466	- Environment defaults to 'staging'
467	- Version defaults to 'latest'
468	```
469
470	### Argument Validation
471
472	```markdown
473	---
474	description: Deploy to validated environment
475	argument-hint: [environment]
476	---
477
478	Environment: $1
479
480	Validating environment...
481
482	valid_envs="dev staging production"
483	if ! echo "$valid_envs" \| grep -w "$1" > /dev/null; then
484	ERROR: Invalid environment '$1'
485	Valid options: dev, staging, production
486	Exit.
487	fi
488
489	Environment validated. Proceeding...
490	```
491
492	### Argument Transformation
493
494	```markdown
495	---
496	description: Deploy with shorthand
497	argument-hint: [env-shorthand]
498	---
499
500	Input: $1
501
502	Expanding shorthand:
503	- d/dev → development
504	- s/stg → staging
505	- p/prod → production
506
507	case "$1" in
508	d\|dev) ENV="development";;
509	s\|stg) ENV="staging";;
510	p\|prod) ENV="production";;
511	*) ENV="$1";;
512	esac
513
514	Deploying to: $ENV
515	```
516
517	## Error Handling in Workflows
518
519	### Graceful Failure
520
521	```markdown
522	---
523	description: Resilient deployment workflow
524	---
525
526	# Deployment Workflow
527
528	Running steps with error handling...
529
530	## Step 1: Tests
531	!`npm test`
532
533	if [ $? -ne 0 ]; then
534	ERROR: Tests failed
535
536	Options:
537	1. Fix tests and retry
538	2. Skip tests (NOT recommended)
539	3. Abort deployment
540
541	What would you like to do?
542
543	[Wait for user input before continuing]
544	fi
545
546	## Step 2: Build
547	[Continue only if Step 1 succeeded]
548	```
549
550	### Rollback on Failure
551
552	```markdown
553	---
554	description: Deployment with rollback
555	---
556
557	# Deploy with Rollback
558
559	Saving current state for rollback...
560	Previous version: !`current-version.sh`
561
562	Deploying new version...
563
564	!`deploy.sh`
565
566	if [ $? -ne 0 ]; then
567	DEPLOYMENT FAILED
568
569	Initiating automatic rollback...
570	!`rollback.sh`
571
572	Rolled back to previous version.
573	Check logs for failure details.
574	fi
575
576	Deployment complete.
577	```
578
579	### Checkpoint Recovery
580
581	```markdown
582	---
583	description: Workflow with checkpoints
584	---
585
586	# Multi-Stage Deployment
587
588	## Checkpoint 1: Validation
589	!`validate.sh`
590	echo "checkpoint:validation" >> .claude/deployment-checkpoints.log
591
592	## Checkpoint 2: Build
593	!`build.sh`
594	echo "checkpoint:build" >> .claude/deployment-checkpoints.log
595
596	## Checkpoint 3: Deploy
597	!`deploy.sh`
598	echo "checkpoint:deploy" >> .claude/deployment-checkpoints.log
599
600	If any step fails, resume with:
601	/deployment-resume [last-successful-checkpoint]
602	```
603
604	## Best Practices
605
606	### Workflow Design
607
608	1. Clear progression: Number steps, show current position
609	2. Explicit state: Don't rely on implicit state
610	3. User control: Provide decision points
611	4. Error recovery: Handle failures gracefully
612	5. Progress indication: Show what's done, what's pending
613
614	### Command Composition
615
616	1. Single responsibility: Each command does one thing well
617	2. Composable design: Commands work together easily
618	3. Standard interfaces: Consistent input/output formats
619	4. Loose coupling: Commands don't depend on each other's internals
620
621	### State Management
622
623	1. Persistent state: Use .local.md files
624	2. Atomic updates: Write complete state files atomically
625	3. State validation: Check state file format/completeness
626	4. Cleanup: Remove stale state files
627	5. Documentation: Document state file formats
628
629	### Error Handling
630
631	1. Fail fast: Detect errors early
632	2. Clear messages: Explain what went wrong
633	3. Recovery options: Provide clear next steps
634	4. State preservation: Keep state for recovery
635	5. Rollback capability: Support undoing changes
636
637	## Example: Complete Deployment Workflow
638
639	### Initialize Command
640
641	```markdown
642	---
643	description: Initialize deployment
644	argument-hint: [environment]
645	allowed-tools: Write, Bash(git:*)
646	---
647
648	# Initialize Deployment to $1
649
650	Creating workflow state...
651
652	\`\`\`yaml
653	---
654	workflow: deployment
655	environment: $1
656	branch: !`git branch --show-current`
657	commit: !`git rev-parse HEAD`
658	stage: initialized
659	timestamp: !`date -u +%Y-%m-%dT%H:%M:%SZ`
660	---
661	\`\`\`
662
663	Written to .claude/deployment-state.local.md
664
665	Next: Run /deployment-validate
666	```
667
668	### Validation Command
669
670	```markdown
671	---
672	description: Validate deployment
673	allowed-tools: Read, Bash
674	---
675
676	Reading state: @.claude/deployment-state.local.md
677
678	Running validation...
679	- Branch check: PASS
680	- Tests: PASS
681	- Build: PASS
682
683	Updating state to 'validated'...
684
685	Next: Run /deployment-execute
686	```
687
688	### Execution Command
689
690	```markdown
691	---
692	description: Execute deployment
693	allowed-tools: Read, Bash, Write
694	---
695
696	Reading state: @.claude/deployment-state.local.md
697
698	Executing deployment to [environment]...
699
700	!`deploy.sh [environment]`
701
702	Deployment complete.
703	Updating state to 'completed'...
704
705	Cleanup: /deployment-cleanup
706	```
707
708	### Cleanup Command
709
710	```markdown
711	---
712	description: Clean up deployment
713	allowed-tools: Bash
714	---
715
716	Removing deployment state...
717	rm .claude/deployment-state.local.md
718
719	Deployment workflow complete.
720	```
721
722	This complete workflow demonstrates state management, sequential execution, error handling, and clean separation of concerns across multiple commands.