Essential Claude Code workflow and context engineering tools for productive development
- version
- 1.12.4
- GitHub stars
- 7
Install
/plugin install base@vibekitRun it inside Claude Code after adding the marketplace with /plugin marketplace add shrwnsan/vibekit-claude-plugins.
Contents
Discovered from sourceSkills 4
Branch & Worktree Hygiene
Classifies every local/remote branch and worktree against the mainline, then cleans up what is resolved. Never guesses — every deletion is backed by a verified verdict.
The core problem
git branch --merged is useless in squash-merge workflows: it reports
nothing mergeable even when branches are fully resolved (content landed via
squashed PRs). The only reliable test is content-level: PR-number log matching,
file presence, and feature greps.
Workflow
-
Classify — run the read-only classifier:
sh <skill-dir>/scripts/classify-branches.sh [mainline-ref]Default mainline:
main(falls back tomaster). Emits one line per item:<verdict> <kind> <ref-or-path> <evidence> -
Verify — the classifier's output is evidence, not authority. Before acting on any verdict, spot-check it: open the cited PR commit, diff the named files, confirm the feature grep. Classifiers hallucinate less than models but more than never.
-
Act per tier:
Verdict Action Confirmation merged-ancestry/merged-content(branch)git branch -Dnone (reflog recovers) remote-gone(local branch, upstream deleted)git branch -D+ remove any worktreenone stale-base(branch predates mainline; merging would regress)surface to user user decides stale-baseis currently emitted by review judgment, not the classifier — treat divergence without squash evidence asunmergedand assess manually. |superseded(content landed, mainline evolved past it) | surface to user | user decides | |unmerged(genuinely unique commits) | surface to user, never delete | user decides | |worktree-prunable(directory gone, registry entry remains) |git worktree prune| none (metadata only) | |worktree-clean-merged(clean tree, branch resolved) |git worktree remove| always confirm (deletes a directory) | |worktree-dirty/worktree-unmerged| never touch | — | |orphan-dir(looks like a worktree, not registered) | surface, move withtrashon confirm | user decides | -
Remote branches — deleting
origin/*refs is outward-facing: list them with verdicts, delete only after explicit user approval, in one batch push.
Squash-merge detection (how the classifier thinks)
For each branch not mergeable by ancestry:
- Extract its commit subjects; grep mainline log for the same subjects with
(#N)suffixes — squash-merges preserve the subject. - Check file presence: key files the branch adds, present on mainline?
- Feature greps: distinctive strings from the branch's diff, present in
mainline's version of those files?
All three hit →
merged-content. Content present but mainline's copy is larger/newer →superseded. Diff would remove lines mainline has →stale-base.
Worktree specifics
git worktree list --porcelainis the source of truth; each entry'sbranchor detachedHEADgets the same verdict engine as free branches.- Detached-HEAD worktrees: verdict keyed on the commit —
merged-ancestryif contained in mainline and tree is clean. - Tool-created worktrees (e.g.
.claude/worktrees/) are included; their auto-cleanup is best-effort, this is the backstop.
Known limitations
- Origin only: the remote scan covers
origin/*exclusively. Repos with additional remotes (upstream/,fork/) only get their origin refs classified — run with awareness, or extend the remote loop. - Squash-merge detection is heuristic: subject matching can false-positive on generic subjects ("fix bugs"); the verify step exists for exactly this reason. Never trust a verdict without checking its evidence.
Hard rules
- The classifier script is read-only — it never deletes, pushes, or prunes.
- Dirty worktrees and
unmergedrefs are never modified, only reported. git worktree removeand remote ref deletion always require user confirmation.- Use
trash, neverrm -rf, for orphaned directories.
Crafting Git Commits
A professional git commit message drafting service that follows modern conventional commit standards, provides collaborative attribution, and includes quality validation for reliable development workflows.
This skill follows the principle of progressive disclosure. This file contains the core workflow and high-level guidance. For more detailed information, please refer to the linked reference files.
Core Workflow
-
Analysis: I start by analyzing the staged changes to understand the context.
git statusgit diff --stagedgit log --oneline -5git branch --show-current
These four commands supply the working-tree state, staged diff, recent style, and branch context.
-
Planning: I identify the commit type, scope, and assess any potential impact, including breaking changes.
-
Validation: I use a detailed checklist to ensure the commit message meets all quality standards. See validation.md for the full checklist.
-
Execution: I draft the commit message, add attribution, and execute the commit, verifying it in the git history.
Reference Documents
For detailed information, please refer to these files:
- examples.md: A comprehensive list of commit message examples for different scenarios (features, bug fixes, docs, etc.).
- validation.md: Detailed checklists for validating commits at all freedom levels.
- patterns.md: Advanced patterns, formatting best practices, attribution guidelines, and freedom levels.
- troubleshooting.md: A guide to common Git errors and recovery procedures.
Utility Scripts
This skill includes executable scripts for validation and analysis.
scripts/validate_commit.sh: Checks if a commit message follows the conventional commit format.scripts/check_attribution.sh: Validates theCo-Authored-Byformat in a commit message.scripts/analyze_changes.sh: Provides a summary of staged changes to help draft a commit message.
System Requirements
- Git version 2.25.0 or higher
- Bash shell access
- Standard Unix tools (
ls,grep, etc.)
Handoff Context
Generates structured context summaries for seamless thread continuation.
Quick Start
Direct invocation (most reliable):
/handoff-context
Natural language trigger phrases:
- "Handoff and [action]" → continuation workflow
- "Handoff to [agent/skill]" → targeted handoff
- "Start a new thread with this" → explicit continuation
- "Let's handoff" / "Lets handoff" / "Just handoff" → context preservation
Note: The slash command works reliably across all agents. Natural language triggers depend on each agent's semantic understanding.
Configuration
Config File Locations
The handoff-context skill looks for configuration in the following order (highest to lowest priority):
| Priority | Location | Scope | Use Case |
|---|---|---|---|
| 1 | ~/.config/agents/handoff-context-config.yml | Cross-tool | Amp, other AI tools |
| 2 | ~/.claude/handoff-context-config.yml | Claude Code | Claude Code specific |
| 3 | .agents/handoff-context-config.yml | Project-local | Per-project overrides |
| 4 | Built-in defaults | Fallback | Ships with plugin |
Quick Setup
Copy the example config to your preferred location:
# Cross-tool location (recommended for multi-tool users)
mkdir -p ~/.config/agents
cp ~/.claude/plugins/base/skills/handoff-context/handoff-context-config.example.yml \
~/.config/agents/handoff-context-config.yml
# Claude Code specific
cp ~/.claude/plugins/base/skills/handoff-context/handoff-context-config.example.yml \
~/.claude/handoff-context-config.yml
# Project-local
mkdir -p .agents
cp ~/.claude/plugins/base/skills/handoff-context/handoff-context-config.example.yml \
.agents/handoff-context-config.yml
Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
format | string | yaml | Output format: yaml or markdown |
include.learnings | boolean | true | Include learnings section |
include.approaches | boolean | true | Include approaches section (what worked/didn't) |
include.git_state | boolean | true | Include git state (branch, files) |
include.quick_start | boolean | true | Include quick_start section |
confidence.minimum | float | 0.3 | Minimum confidence score floor |
confidence.threshold | float | 0.7 | Warning threshold for low quality |
Example Configuration
# ~/.config/agents/handoff-context-config.yml
# Output format
format: yaml # yaml | markdown
# Include optional sections
include:
learnings: true
approaches: true
git_state: true
quick_start: true
# Confidence scoring thresholds
confidence:
minimum: 0.3 # Floor score (0.3 = tentative, still some value)
threshold: 0.7 # Warning threshold (below = add more context)
Config Metadata in Handoff
Each handoff file includes metadata about which config was used:
metadata:
config:
source: "~/.config/agents/handoff-context-config.yml"
format: "yaml"
Temp Directory Behavior
Handoff files respect the following temp directory priority:
| Environment | Priority | Default Path |
|---|---|---|
| Claude Code | CLAUDE_CODE_TMPDIR (1st) | /tmp/claude/handoff-XXX/ |
| Amp, Droid, others | TMPDIR (2nd) | System temp (e.g., /var/folders/.../T/ on macOS) |
| Fallback | /tmp (3rd) | /tmp/handoff-XXX/ |
Why this priority? Claude Code's sandbox denies direct /tmp/ writes but allows writes to CLAUDE_CODE_TMPDIR (default: /tmp/claude). Other tools respect the standard TMPDIR environment variable.
Typical paths by tool:
- Claude Code:
/tmp/claude/handoff-a1b2c3/handoff-20260111-143022.yaml - Amp (macOS):
/var/folders/xx/.../T/handoff-d4e5f6/handoff-20260111-143022.yaml - Droid (Linux):
/tmp/handoff-g7h8i9/handoff-20260111-143022.yaml
Invocation Method Reliability
| Method | Reliability | Output |
|---|---|---|
/handoff-context | ✅ 100% | YAML file + structured display |
| "Let's handoff" | ⚠️ Variable | May produce text-only or .txt file |
Recommendation: Use /handoff-context for consistent cross-agent behavior.
Workflow Requirements
When this skill is triggered, you MUST follow these steps exactly:
- Execute the script first:
# Find script in plugin cache (works across different directories)
# Alternative locations: ~/.claude/plugins, ~/.agent/skills
bash $(find ~/.claude/plugins -name "capture-context.sh" 2>/dev/null | head -1)
-
Capture the HANDOFF_FILE path from script output (format:
HANDOFF_FILE=/tmp/...) -
Read that file and populate conversation context:
- Current work (tasks, status, affected files)
- Conversation summary (phases, outcomes, decisions)
- Next steps (continuation action context)
- Preserved context (key details to remember)
-
Overwrite the same file with complete context
-
Display summary to user with file path
⚠️ CRITICAL REQUIREMENTS:
- ✅ MUST create .yaml file (not .txt)
- ✅ MUST use YAML format in file (not Markdown)
- ✅ MUST execute script (not bypass with manual commands)
- ✅ MUST display file path with continuation instruction
What the script captures:
- Session tracking (unique ID, timestamps)
- Metadata (confidence score, quality indicators)
- Quick start info (project type, package manager)
- Git state (branch, staged/unstaged/untracked files)
- YAML structure with dynamic timestamps
- Secure temp directory with proper permissions
What you need to add:
- Current work, conversation summary, next steps, preserved_context
- Update confidence_score based on populated content:
- Base: 0.5
- +0.1 if git_state has files
- +0.1 if conversation_summary has 1+ items
- +0.1 if current_work has 1+ items
- +0.1 if next_steps has 1+ items
- +0.1 if continuation_action is not null
- -0.1 for each empty critical section
- Cap: 0.3 minimum, 0.95 maximum
- Populate learnings with patterns/techniques discovered (0.3-0.9 confidence)
- Populate approaches (successful, failed, not attempted)
- Fill session.started and session.duration_minutes
- Fill quick_start fields (verification_command, files_to_read_first, context_priority, estimated_time_minutes)
Result: Complete /tmp/handoff-XXX/handoff-YYYYMMDD-HHMMSS.yaml with full context.
Success Criteria
Before completing handoff, verify:
- Script was executed (find + bash, not manual commands)
- File has .yaml extension (not .txt)
- File contains valid YAML structure (not Markdown with ##)
- File path is shown to user
- Continuation instruction includes exact file path
- Human-readable summary displayed alongside file
- Confidence score ≥ 0.7 (or document reason for lower score)
- Session tracking populated (started, duration_minutes)
- Critical sections filled (current_work, conversation_summary)
If any criteria fails: Re-invoke with /handoff-context slash command.
Quality Thresholds
| Confidence Score | Quality Level | Recommendation |
|---|---|---|
| ≥ 0.9 | Comprehensive | Ready for immediate continuation |
| 0.7 - 0.9 | Good | Acceptable, minor gaps possible |
| 0.5 - 0.7 | Acceptable | Consider adding more context |
| < 0.5 | Needs Work | Add more context before handoff |
What Gets Captured
| Category | Details |
|---|---|
| Session | Unique ID, timestamps, duration (calculated by agent) |
| Metadata | Confidence score (0.3-0.95), quality level, missing context flags |
| Quick Start | Project type, package manager, priority files, estimated time |
| Git State | Branch, staged/unstaged/untracked files |
| Conversation | Phase summaries, outcomes, decisions |
| Current Work | Active tasks with status and affected files |
| Learnings | Patterns discovered, debugging techniques, confidence levels |
| Approaches | What worked, what didn't, what's left to try |
| Next Steps | Continuation action (if specified) |
| Preserved Context | Key decisions and important details |
Example Output
🔄 Handoff ready
Context written to: /tmp/handoff-20260126-143022.yaml
To continue in a new thread:
1. Start a new AI agent conversation
2. Tell the agent: "Continue from /tmp/handoff-20260126-143022.yaml"
Quick Examples
Continuation: "Handoff and build an admin panel" → action extracted Preservation: "Handoff this context" → full state saved Targeted: "Handoff to code-reviewer" → specific agent
Quick reference: See examples.md - 4 concrete scenarios:
- Continuation Handoff - "Handoff and build an admin panel"
- Context Preservation - "Handoff this context"
- Targeted Handoff - "Handoff to code-reviewer for security check"
- Fresh Thread for Next Phase - "Continue in a fresh thread"
Documentation
| File | Purpose |
|---|---|
| references/patterns.md | All trigger patterns and regex matching rules |
| references/workflow.md | Complete step-by-step workflow manual |
| references/examples.md | Quick reference scenarios |
| references/templates.md | YAML template structures |
Evaluations
Test files for validating skill behavior:
- assets/eval-continuation.json
- assets/eval-context-preservation.json
- assets/eval-targeted-handoff.json
- assets/eval-non-git-repo.json
- assets/eval-negative-cases.json - Failure scenario detection
Run evaluations to verify pattern detection, YAML generation, and failure handling.
Common Scenarios
- After implementing a feature → move to next phase in fresh thread
- Long thread → start fresh with preserved context
- Bug fix → audit similar patterns elsewhere
- Planning → implementation transition
Error Handling
| Scenario | Handling |
|---|---|
| Script not found | Follow manual workflow in references/workflow.md |
| Script execution fails | Fall back to manual workflow steps |
| No git repo | Script omits git_state, proceeds with conversation context |
| No action | Script sets continuation_action: null |
| Empty conversation | Script provides minimal context with working directory |
See references/workflow.md for complete manual workflow and error scenarios.
Integration
Works with:
- workflow-orchestrator: Handoff detection during workflow execution
- crafting-commits: Context preservation before committing
- systematic-debugging: Preserves error context during debugging
Philosophy
Seamless continuation without losing context.
No buttons to click, no commands to remember—just say "handoff" and continue working.
Limitations
- Does not automatically create new threads (platform capability)
- Context in
/tmp/may be cleared on system reboot - Git state is captured at handoff time, not live-synced
Use when transitioning to a fresh thread. Skip when the conversation is still manageable.
Systematic Debugging
A systematic approach to debugging that ensures you understand the root cause before attempting fixes. This reduces thrashing, prevents new bugs, and saves time.
When to Use
Use this skill when you encounter:
- Error messages or stack traces in conversation
- Test failures being discussed
- "Not working", "bug", "broken", or "unexpected behavior" mentioned
- Questions like "why is this happening?" or "help me debug"
- User reports something failing after changes
- Performance problems or build failures
This skill provides structure to prevent:
- Random fixes without understanding root cause
- Multiple simultaneous changes that can't be isolated
- Skipping tests and manual verification
- Thrashing when 3+ fixes have failed
Examples
Test Failure
"This test is failing: AssertionError: Expected 200 but got 500"
"help me debug this failing test suite"
"Why is the user auth test suddenly broken?"
Runtime Error
"I'm getting TypeError: Cannot read property 'x' of undefined"
"This worked yesterday but now throws an error"
"Something's broken after my refactor"
Build/CI Issues
"The CI pipeline is failing randomly"
"Build works locally but fails in production"
"Getting intermittent failures in our deployment"
Core Workflow
1. Capture Error Context
Gather information about the problem:
- Read error messages and stack traces completely
- Note line numbers, file paths, error codes
- Check logs for additional context
- Understand what the system is telling you
Quick context sweep — run these before forming a hypothesis:
git log --oneline -5 # recent commits
find . -name "*.log" -mtime -1 2>/dev/null | head -5 # recent logs
find . \( -name 'build*.log' -o -name 'webpack*.log' \) -mtime -1 2>/dev/null | head -3 # recent build output
2. Identify Reproduction Steps
Can you trigger the issue reliably?
- What are the exact steps to reproduce?
- Does it happen every time or intermittently?
- What conditions trigger it?
- If not reproducible: gather more data, don't guess
3. Isolate Failure Location
Where exactly does the problem occur?
- Trace the data flow to find where it breaks
- Check recent changes that could cause this
- Use diagnostic logging for multi-component systems
- Identify the specific component or function failing
4. Implement Minimal Fix
Address the root cause, not the symptom:
- Form a clear hypothesis: "I think X is causing this because Y"
- Make the smallest possible change to test
- One variable at a time
- No "while I'm here" improvements
5. Verify Solution
Confirm it actually works:
- Does the fix resolve the issue?
- Are tests passing?
- No other tests broken?
- Can you still reproduce the problem?
⚠️ Stop Signs: Read Before Proceeding
If you catch yourself thinking any of these, STOP and return to step 1:
| Thought | What To Do Instead |
|---|---|
| "Quick fix for now, investigate later" | Investigate now. Quick fixes create new bugs. |
| "Just try changing X and see if it works" | Form a hypothesis first. Test one variable at a time. |
| "Add multiple changes, run tests" | One change at a time. Otherwise you can't isolate what worked. |
| "Skip the test, I'll manually verify" | Write the test. Untested fixes don't stick. |
| "It's probably X, let me fix that" | Verify X is the root cause before fixing. |
| "One more fix attempt" (after 2+ failures) | Stop. 3+ failed fixes usually means architectural problem. |
When You've Tried 3+ Fixes
Pattern indicating deeper problem:
- Each fix reveals a new issue elsewhere
- Fixes require massive refactoring to implement
- You're fixing symptoms, not root cause
- Each "solution" creates new problems
Stop and question fundamentals:
- Is this approach fundamentally sound?
- Should we refactor architecture instead?
- Are we "sticking with it through sheer inertia"?
- Discuss with user before attempting Fix #4
This is not a failed hypothesis—this is likely a wrong architecture.
For Multi-Component Systems
When debugging across layers (CI → build → deploy, API → service → database):
Add diagnostic logging at each boundary before fixing:
# At each component boundary:
# - Log what data enters the component
# - Log what data exits the component
# - Verify environment/config propagation
# - Check state at each layer
# Run once to identify WHERE it breaks
# THEN analyze evidence to identify failing component
# THEN investigate that specific component
Example (multi-layer system):
# Layer 1: Workflow
echo "=== Secrets available in workflow: ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
# Layer 2: Build script
echo "=== Env vars in build script: ==="
env | grep IDENTITY || echo "IDENTITY not in environment"
# Layer 3: Signing script
echo "=== Keychain state: ==="
security list-keychains
security find-identity -v
# This reveals: Which layer fails
Common Debugging Pitfalls
| Pitfall | Why It's Problematic | Better Approach |
|---|---|---|
| Fixing without understanding | You treat symptoms, not causes | Always identify root cause first |
| Multiple changes at once | Can't isolate what worked | One variable at a time |
| Assuming without verifying | Wastes time on wrong fixes | Verify hypotheses with data |
| Skipping tests | Fixes don't stick | Write tests before fixing |
| Ignoring error messages | Solutions often in the error | Read errors completely |
| Rushing under pressure | Guarantees rework | Systematic is faster than thrashing |
What Success Looks Like
✅ You understand exactly WHAT is broken and WHY ✅ You can reproduce the issue consistently ✅ Your fix addresses root cause, not symptom ✅ Tests pass and issue is resolved ✅ No new bugs introduced ✅ You've prevented similar issues
Integration with Base Plugin
This skill works alongside other Base plugin capabilities:
- crafting-commits: Document debugging findings in commit messages
- workflow-orchestrator: Coordinate debugging workflows with quality gates
- /commit: Create commits that reference resolved issues
Philosophy
Systematic debugging is faster than random fixes.
From real debugging sessions:
- Systematic approach: 15-30 minutes to fix
- Random fixes approach: 2-3 hours of thrashing
- First-time fix rate: 95% vs 40%
- New bugs introduced: Near zero vs common
Core principle: Understand before you fix.
Limitations
- Requires reproducible issues for systematic investigation
- Intermittent/timing-dependent bugs may need additional monitoring strategies
- Environmental issues (external dependencies, network) may not have root causes in code
- Complex distributed systems may require specialized debugging tools beyond this scope
- Not a substitute for proper logging, observability, and monitoring infrastructure
Rationale: This skill provides systematic debugging structure while remaining pragmatic. Use when helpful, adapt to the situation, skip when the issue is straightforward.
Commands 2
Git Commit Creation
Your task
Create a git commit following this workflow:
Step 1: Analysis
First, run these commands to understand the current state:
- Check git status
- Review all changes (staged and unstaged)
- Check recent commit style
Then:
- Review all changes (staged and unstaged)
- Identify change patterns and complexity level
- Check for potential breaking changes
- Match commit style with recent commits
Step 2: Determine Mode and Route
First, check for explicit mode flags in arguments:
-for--fast: Force Route A (Simple) regardless of change type-vor--verbose: Force Route B (Detailed) regardless of change type- No flags: Auto-determine based on change complexity
Route A (Simple) - For changes matching these patterns:
- Documentation updates (
docs:) - Style/formatting fixes (
style:) - Simple bug fixes (
fix:) - Chore/maintenance (
chore:) - Test additions/updates (
test:)
Route B (Detailed) - For changes requiring:
- Feature additions (
feat:) - Refactoring (
refactor:) - Performance improvements (
perf:) - Breaking changes (with exclamation mark)
- Detailed explanations needed
Step 3: Execute Route
Route A: Simple Commit (autonomous)
- Stage relevant unstaged changes
- Create commit message following conventional format
- Ask user: "Please review the commit message above. Should I proceed with this commit?"
- Execute commit
- Verify success
Route B: Detailed Commit (with comprehensive analysis)
- Analyze changes: Determine commit type and scope based on actual changes
- Check for breaking changes: Identify API changes, removed features, or incompatible modifications
- Show files to be committed: List specific files that will be included in this commit
- Propose commit details:
- Recommend commit type (feat, fix, refactor, etc.)
- Identify if breaking changes exist and need highlighting
- Suggest scope if applicable
- Ask user: "I recommend [type] for these files: [file list]. [Breaking/No breaking] changes detected. Should I proceed?"
- Stage relevant unstaged changes
- Create detailed commit message with body and proper breaking change formatting
- Ask user: "Please review the commit message above. Should I proceed with this commit?"
- Execute commit
- Verify success
Step 4: Quality Checks
Always ensure:
- Subject line under 50 characters, imperative mood
- Proper conventional commit format
- No secrets committed (.env, credentials.json, etc.)
Custom Message Support
If user provided arguments, incorporate their message while maintaining conventional commit format and quality standards.
Final Output
Show:
- Commit message that was used
- Files that were committed
- Git status after commit
- Next step suggestions
Goal: Build a deep, end-to-end understanding of this app and its architecture, then produce an actionable architecture review.
Context constraints
- Use only what you see in the code and what I explicitly tell you; if unclear, ask instead of guessing.
- Prefer architecture/runtime/data-flow insights over nitpicks.
- Keep the response under ~700 words unless I ask for a deeper dive.
- Analysis focus
- Identify major components, responsibilities, and dependencies.
- Map key data flows for core user journeys or background jobs.
- Note risks/smells (security, performance, reliability, DX).
- Deliverables
- 5–10 bullet high-level architecture summary.
- Step-by-step primary flow(s).
- Top improvement opportunities (prioritized) with 1-line rationale each.
- Visual diagrams (optional) After delivering the initial review, ask: "Would you like me to generate state machine diagrams for the key components? This helps verify complete path coverage and reveals edge cases."
If yes, create diagrams in TWO formats:
3.1. Terminal format (compact ASCII, for immediate viewing):
- Section headers for grouping (Main Flow, Error Handling, Concurrent Operations)
- State labels in brackets: ①[StateName]
- Clear entry/exit markers: START, EXIT
- Explicit loop markers: "→ back to ①" or "→ retry"
- Box-drawing for hierarchies: ├─, │, └─
- Keep compact and readable in terminal width
3.2. Markdown format (for file output with rendering):
- Mermaid diagram syntax:
mermaid ... - Use stateDiagram-v2 for state machines
- Use flowchart TD for data flows and process flows
- Include descriptive labels and proper transitions
- Full documentation with diagram descriptions
After generating terminal format, ask: "Should I write this to a file as Markdown with Mermaid diagrams? (Recommended for GitHub/IDE rendering)"
- Guardrails
- Do not invent services/APIs/infra not present; mark unknown and ask.
- No speculative metrics; keep it qualitative unless concrete data exists.
- Don't paste large code blocks unless asked.
- File exclusion: NEVER read system files (.DS_Store, Thumbs.db, desktop.ini, *.swp, *~, etc.) or editor configs (.idea/, .vscode/, .sublime-)
- Security exclusion: NEVER read or display contents of secrets files (.env, .env.*, *.key, *.pem, credentials.json, .aws/credentials, etc.)
- Sensitive data: If you encounter API keys, tokens, or secrets in code, report their presence generically without exposing values
- End pattern
- End with a section titled “Next, I recommend we…” and list 2–3 concrete next steps.
Optional focus: $ARGUMENTS
Agents 1
Workflow Orchestrator
Purpose-built subagent for coordinating and orchestrating development workflows within the base plugin ecosystem. It manages git workflows, quality gate integration, parallel development coordination, and task sequencing to ensure smooth development processes.
Inputs
- Workflow type: standard, parallel, qa, cleanup
- Scope: feature development, bug fixes, documentation, chores
- Requirements: quality level, parallel agents, specific constraints
- Context: current branch, staged changes, project structure
Outputs
Structured workflow execution with:
- Status: workflow progress and completion state
- Actions taken: list of executed operations and their results
- Quality results: test outcomes, linting results, validation status
- Recommendations: next steps, follow-up actions, improvements needed
Operating Procedure (Runbook)
- Analyze workflow request
- Identify workflow type (standard, parallel, qa, cleanup)
- Determine scope and requirements from context
- Assess current git state and branch status
- Evaluate quality requirements based on changes
- Prepare workflow environment
- Verify git working directory state
- Check for necessary tools and dependencies
- Validate branch/worktree setup if parallel workflow
- Ensure quality gates are properly configured
- Execute primary workflow
- Standard: git add → commit message crafting → commit → basic checks
- Parallel: worktree setup → subagent coordination → merge preparation
- QA: scoped quality checks → validation → reporting
- Cleanup: trash operations → cache clearing → state reset
- Coordinate integration points
- Integrate git commit crafter for proper message formatting
- Apply systematic debugging approach when errors occur
- Coordinate quality gate execution at appropriate stages
- Manage parallel subagent contexts and isolation
- Utilize terminal helpers for productivity enhancements
- Integrate handoff-context skill for seamless thread transitions
- Quality assurance integration
- Run scoped quality checks based on commit type
- Validate test coverage and linting status
- Check documentation completeness for relevant changes
- Verify build success and performance impact
- Progress tracking and reporting
- Monitor workflow execution status
- Track action completion and results
- Generate comprehensive status reports
- Provide recommendations for next steps
- Error handling and recovery
- Apply systematic debugging when errors or test failures occur
- Handle workflow interruptions gracefully
- Provide recovery options for failed operations
- Maintain workflow state for resume capability
- Document issues and resolution steps
- Handoff detection and coordination
- Detect natural language handoff triggers in user requests during workflow execution
- When handoff detected: invoke handoff-context skill to capture current state
- Capture workflow state, git context, and conversation summary
- Output structured handoff payload for thread continuation
- Preserve workflow state for resumption in new thread
- Support handoff triggers during any workflow phase (planning, execution, QA)
Error Handling Policy
- Git conflicts: Provide conflict resolution guidance and merge strategies
- Quality failures: Detail specific issues and remediation steps
- Parallel sync issues: Coordinate worktree synchronization and merge planning
- Tool failures: Suggest alternative approaches and manual workarounds
- State corruption: Recommend recovery from known good states
Decision Heuristics
- Feature changes → full QA workflow + documentation checks
- Bug fixes → targeted testing + regression validation
- Documentation changes → link checking + formatting validation
- Chore/maintenance → minimal checks + syntax validation
- Breaking changes → comprehensive QA + documentation updates
Stop Conditions
- Workflow completed successfully with all required actions executed
- Irrecoverable error encountered with clear resolution path provided
- User intervention required with specific guidance given
- Quality gates failed with detailed remediation steps provided
Escalation
- Complex merge conflicts requiring manual resolution guidance
- Quality failures requiring architectural decisions
- Workflow state corruption requiring complete reset
- Parallel development conflicts requiring coordination strategies
Do / Don't
- Do validate git state before starting workflows
- Do provide clear, actionable error messages and recovery steps
- Do coordinate quality checks appropriately for change scope
- Do maintain workflow state for resume capability
- Don't execute destructive operations without explicit confirmation
- Don't proceed with workflows when critical preconditions aren't met
- Don't ignore quality gate failures or validation errors
- Don't create parallel workflows without proper isolation setup
Examples
- Standard workflow: "Commit new user authentication feature with proper quality checks"
- Parallel workflow: "Coordinate two feature branches with isolated development environments"
- QA workflow: "Run comprehensive quality assurance on database schema changes"
- Cleanup workflow: "Clean up development environment and reset working directory state"
Notes
- Inherits parent context tools for full workflow orchestration capabilities
- Maintains awareness of git state and branch context for coordinated operations
- Integrates with base plugin skills for comprehensive workflow management
- Provides detailed progress tracking and status reporting for transparency
Hooks 1
Sponsors
Details
- Marketplace
- shrwnsan/vibekit-claude-plugins
- Source
- plugins/base
- Author
- shrwnsan
- Category
- Productivity
- License
- Apache-2.0
- Keywords
- claude-code, git, workflow, productivity, git-commit, quality-assurance, terminal, development-tools, workflow-automation, debugging
