Essential Claude Code workflow and context engineering tools for productive development

version
1.12.4
GitHub stars
7

Install

/plugin install base@vibekit

Run it inside Claude Code after adding the marketplace with /plugin marketplace add shrwnsan/vibekit-claude-plugins.

Contents

Discovered from source

Skills 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

  1. Classify — run the read-only classifier:

    sh <skill-dir>/scripts/classify-branches.sh [mainline-ref]
    

    Default mainline: main (falls back to master). Emits one line per item: <verdict> <kind> <ref-or-path> <evidence>

  2. 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.

  3. Act per tier:

    VerdictActionConfirmation
    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 useruser decides

    stale-base is currently emitted by review judgment, not the classifier — treat divergence without squash evidence as unmerged and 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 with trash on confirm | user decides |

  4. 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:

  1. Extract its commit subjects; grep mainline log for the same subjects with (#N) suffixes — squash-merges preserve the subject.
  2. Check file presence: key files the branch adds, present on mainline?
  3. 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 --porcelain is the source of truth; each entry's branch or detached HEAD gets the same verdict engine as free branches.
  • Detached-HEAD worktrees: verdict keyed on the commit — merged-ancestry if 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 unmerged refs are never modified, only reported.
  • git worktree remove and remote ref deletion always require user confirmation.
  • Use trash, never rm -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

  1. Analysis: I start by analyzing the staged changes to understand the context.

    • git status
    • git diff --staged
    • git log --oneline -5
    • git branch --show-current

    These four commands supply the working-tree state, staged diff, recent style, and branch context.

  2. Planning: I identify the commit type, scope, and assess any potential impact, including breaking changes.

  3. Validation: I use a detailed checklist to ensure the commit message meets all quality standards. See validation.md for the full checklist.

  4. 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 the Co-Authored-By format 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):

PriorityLocationScopeUse Case
1~/.config/agents/handoff-context-config.ymlCross-toolAmp, other AI tools
2~/.claude/handoff-context-config.ymlClaude CodeClaude Code specific
3.agents/handoff-context-config.ymlProject-localPer-project overrides
4Built-in defaultsFallbackShips 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

OptionTypeDefaultDescription
formatstringyamlOutput format: yaml or markdown
include.learningsbooleantrueInclude learnings section
include.approachesbooleantrueInclude approaches section (what worked/didn't)
include.git_statebooleantrueInclude git state (branch, files)
include.quick_startbooleantrueInclude quick_start section
confidence.minimumfloat0.3Minimum confidence score floor
confidence.thresholdfloat0.7Warning 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:

EnvironmentPriorityDefault Path
Claude CodeCLAUDE_CODE_TMPDIR (1st)/tmp/claude/handoff-XXX/
Amp, Droid, othersTMPDIR (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

MethodReliabilityOutput
/handoff-context✅ 100%YAML file + structured display
"Let's handoff"⚠️ VariableMay 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:

  1. 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)
  1. Capture the HANDOFF_FILE path from script output (format: HANDOFF_FILE=/tmp/...)

  2. 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)
  3. Overwrite the same file with complete context

  4. 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 ScoreQuality LevelRecommendation
≥ 0.9ComprehensiveReady for immediate continuation
0.7 - 0.9GoodAcceptable, minor gaps possible
0.5 - 0.7AcceptableConsider adding more context
< 0.5Needs WorkAdd more context before handoff

What Gets Captured

CategoryDetails
SessionUnique ID, timestamps, duration (calculated by agent)
MetadataConfidence score (0.3-0.95), quality level, missing context flags
Quick StartProject type, package manager, priority files, estimated time
Git StateBranch, staged/unstaged/untracked files
ConversationPhase summaries, outcomes, decisions
Current WorkActive tasks with status and affected files
LearningsPatterns discovered, debugging techniques, confidence levels
ApproachesWhat worked, what didn't, what's left to try
Next StepsContinuation action (if specified)
Preserved ContextKey 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:

  1. Continuation Handoff - "Handoff and build an admin panel"
  2. Context Preservation - "Handoff this context"
  3. Targeted Handoff - "Handoff to code-reviewer for security check"
  4. Fresh Thread for Next Phase - "Continue in a fresh thread"

Documentation

FilePurpose
references/patterns.mdAll trigger patterns and regex matching rules
references/workflow.mdComplete step-by-step workflow manual
references/examples.mdQuick reference scenarios
references/templates.mdYAML template structures

Evaluations

Test files for validating skill behavior:

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

ScenarioHandling
Script not foundFollow manual workflow in references/workflow.md
Script execution failsFall back to manual workflow steps
No git repoScript omits git_state, proceeds with conversation context
No actionScript sets continuation_action: null
Empty conversationScript 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:

ThoughtWhat 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

PitfallWhy It's ProblematicBetter Approach
Fixing without understandingYou treat symptoms, not causesAlways identify root cause first
Multiple changes at onceCan't isolate what workedOne variable at a time
Assuming without verifyingWastes time on wrong fixesVerify hypotheses with data
Skipping testsFixes don't stickWrite tests before fixing
Ignoring error messagesSolutions often in the errorRead errors completely
Rushing under pressureGuarantees reworkSystematic 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:

  1. Check git status
  2. Review all changes (staged and unstaged)
  3. Check recent commit style

Then:

  1. Review all changes (staged and unstaged)
  2. Identify change patterns and complexity level
  3. Check for potential breaking changes
  4. Match commit style with recent commits

Step 2: Determine Mode and Route

First, check for explicit mode flags in arguments:

  • -f or --fast: Force Route A (Simple) regardless of change type
  • -v or --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)
  1. Stage relevant unstaged changes
  2. Create commit message following conventional format
  3. Ask user: "Please review the commit message above. Should I proceed with this commit?"
  4. Execute commit
  5. Verify success
Route B: Detailed Commit (with comprehensive analysis)
  1. Analyze changes: Determine commit type and scope based on actual changes
  2. Check for breaking changes: Identify API changes, removed features, or incompatible modifications
  3. Show files to be committed: List specific files that will be included in this commit
  4. Propose commit details:
    • Recommend commit type (feat, fix, refactor, etc.)
    • Identify if breaking changes exist and need highlighting
    • Suggest scope if applicable
  5. Ask user: "I recommend [type] for these files: [file list]. [Breaking/No breaking] changes detected. Should I proceed?"
  6. Stage relevant unstaged changes
  7. Create detailed commit message with body and proper breaking change formatting
  8. Ask user: "Please review the commit message above. Should I proceed with this commit?"
  9. Execute commit
  10. 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.
  1. 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).
  1. Deliverables
  • 5–10 bullet high-level architecture summary.
  • Step-by-step primary flow(s).
  • Top improvement opportunities (prioritized) with 1-line rationale each.
  1. 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)"

  1. 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
  1. 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)

  1. 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
  1. 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
  1. 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
  1. 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
  1. 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
  1. Progress tracking and reporting
  • Monitor workflow execution status
  • Track action completion and results
  • Generate comprehensive status reports
  • Provide recommendations for next steps
  1. 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
  1. 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

More from shrwnsan/vibekit-claude-plugins

All 6