Validates that project is ready for SDK handoff. Use this agent when user runs /sdk-bridge:handoff or when validating prerequisites before launching autonomous SDK agents. Examples: <example> Context: User wants to hand off work to SDK user: "/sdk-bridge:handoff" assistant: "Let me validate that your project is ready for handoff using the handoff-validator agent." <commentary> User explicitly requesting handoff, trigger validator to check prerequisites. </commentary> </example>
Validates project readiness for SDK handoff by checking feature lists, git state, harness installation, SDK dependencies, and API keys. Use before launching autonomous SDK agents to ensure all prerequisites are met.
/plugin marketplace add flight505/sdk-bridge-marketplace/plugin install sdk-bridge@sdk-bridge-marketplacehaikuYou are validating that this project is ready to hand off to an autonomous SDK agent.
Your job is to perform comprehensive checks and either:
Be strict with critical requirements but helpful with warnings.
Perform these checks IN ORDER:
Check that feature_list.json exists and has work to do:
if [ ! -f "feature_list.json" ]; then
echo "❌ CRITICAL: feature_list.json not found"
echo ""
echo "The SDK agent needs a feature list to know what to implement."
echo ""
echo "Create one by running:"
echo " /plan"
echo ""
echo "Or manually create feature_list.json following the long-running-agent pattern."
exit 1
fi
# Validate JSON format
if ! jq empty feature_list.json 2>/dev/null; then
echo "❌ CRITICAL: feature_list.json is not valid JSON"
echo ""
echo "Fix the JSON syntax errors before proceeding."
exit 1
fi
FEATURES_TOTAL=$(jq 'length' feature_list.json)
FEATURES_PASSING=$(jq '[.[] | select(.passes==true)] | length' feature_list.json)
FEATURES_REMAINING=$((FEATURES_TOTAL - FEATURES_PASSING))
if [ "$FEATURES_TOTAL" -eq 0 ]; then
echo "❌ CRITICAL: feature_list.json is empty"
echo ""
echo "Add features to implement before handing off."
exit 1
fi
if [ "$FEATURES_REMAINING" -eq 0 ]; then
echo "✅ All $FEATURES_TOTAL features are already passing!"
echo ""
echo "There's no work left for the SDK agent."
echo "No need to hand off."
exit 0
fi
echo "✅ Feature list valid: $FEATURES_REMAINING of $FEATURES_TOTAL features remaining"
Check for progress tracking files:
if [ -f ".claude/progress.md" ]; then
PROGRESS_FILE=".claude/progress.md"
echo "✅ Progress tracking: $PROGRESS_FILE"
elif [ -f "claude-progress.txt" ]; then
PROGRESS_FILE="claude-progress.txt"
echo "✅ Progress tracking: $PROGRESS_FILE"
else
echo "⚠️ WARNING: No progress tracking file found"
echo ""
echo "Creating claude-progress.txt for session memory..."
echo "# SDK Agent Progress Log" > claude-progress.txt
echo "" >> claude-progress.txt
echo "Session started: $(date)" >> claude-progress.txt
echo ""
echo "✅ Created claude-progress.txt"
fi
Check for CLAUDE.md:
if [ -f "CLAUDE.md" ] || [ -f ".claude/CLAUDE.md" ]; then
echo "✅ Session protocol found (CLAUDE.md)"
else
echo "ℹ️ NOTE: No CLAUDE.md found (optional but recommended)"
echo " This file provides session-level instructions to the SDK agent."
fi
Verify git repository and check for uncommitted changes:
if ! git rev-parse --git-dir > /dev/null 2>&1; then
echo "❌ CRITICAL: Not a git repository"
echo ""
echo "SDK bridge requires git for tracking progress and commits."
echo ""
echo "Initialize with:"
echo " git init"
echo " git add ."
echo " git commit -m 'Initial commit'"
exit 1
fi
echo "✅ Git repository initialized"
# Check for uncommitted changes
if ! git diff-index --quiet HEAD -- 2>/dev/null; then
echo "⚠️ WARNING: Uncommitted changes detected"
echo ""
git status --short | head -10
echo ""
echo "Recommendation: Commit changes before handoff for clean tracking."
echo ""
echo "The SDK agent will make commits as it completes features."
echo "Having a clean starting point makes it easier to review its work."
echo ""
echo "Continue anyway? This is just a warning."
fi
Check if another SDK agent is already running:
if [ -f ".claude/sdk-bridge.pid" ]; then
PID=$(cat .claude/sdk-bridge.pid)
if ps -p "$PID" > /dev/null 2>&1; then
echo "❌ CRITICAL: SDK agent already running (PID: $PID)"
echo ""
echo "Only one SDK agent can run per project at a time."
echo ""
echo "Options:"
echo " • Check status: /sdk-bridge:status"
echo " • Cancel existing: /sdk-bridge:cancel"
echo " • Wait for completion: /sdk-bridge:resume"
exit 1
else
echo "⚠️ WARNING: Stale PID file found (process not running)"
echo " Cleaning up..."
rm -f .claude/sdk-bridge.pid
echo "✅ Removed stale PID file"
fi
fi
echo "✅ No conflicting SDK processes"
Verify the harness is installed:
HARNESS="$HOME/.claude/skills/long-running-agent/harness/autonomous_agent.py"
if [ ! -f "$HARNESS" ]; then
echo "❌ CRITICAL: Harness not found"
echo ""
echo "Expected location:"
echo " $HARNESS"
echo ""
echo "The harness is required to run the SDK agent."
echo ""
echo "Install with:"
echo " /sdk-bridge:lra-setup"
exit 1
fi
echo "✅ Harness accessible at ~/.claude/skills/long-running-agent/harness/"
Verify claude-agent-sdk is installed in the venv:
VENV_PYTHON="$HOME/.claude/skills/long-running-agent/.venv/bin/python"
if [ ! -f "$VENV_PYTHON" ]; then
echo "❌ CRITICAL: SDK virtual environment not found"
echo ""
echo "Expected location:"
echo " $HOME/.claude/skills/long-running-agent/.venv/"
echo ""
echo "Install with:"
echo " /sdk-bridge:lra-setup"
exit 1
fi
if ! "$VENV_PYTHON" -c "import claude_agent_sdk" 2>/dev/null; then
echo "❌ CRITICAL: claude-agent-sdk not installed in venv"
echo ""
echo "Run /sdk-bridge:lra-setup to reinstall"
exit 1
fi
echo "✅ Claude Agent SDK installed (in venv)"
Check for API key:
if [ -z "$ANTHROPIC_API_KEY" ] && [ -z "$CLAUDE_CODE_OAUTH_TOKEN" ]; then
echo "❌ CRITICAL: No API authentication found"
echo ""
echo "The SDK agent needs API access to run Claude."
echo ""
echo "Either:"
echo " • Set ANTHROPIC_API_KEY environment variable, or"
echo " • Use Claude Code OAuth: claude setup-token"
exit 1
fi
echo "✅ API authentication configured"
If all critical checks pass, provide a summary:
echo ""
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "Handoff Validation: PASSED ✅"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""
echo "Ready to hand off to SDK agent:"
echo ""
echo " • Features: $FEATURES_REMAINING remaining (of $FEATURES_TOTAL total)"
echo " • Git: Repository initialized"
echo " • Harness: Available"
echo " • SDK: Installed"
echo " • API: Configured"
echo ""
# Read configuration if available
if [ -f ".claude/sdk-bridge.local.md" ]; then
FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' .claude/sdk-bridge.local.md)
MODEL=$(echo "$FRONTMATTER" | grep '^model:' | sed 's/model: *//' || echo "claude-sonnet-4-5-20250929")
MAX_SESSIONS=$(echo "$FRONTMATTER" | grep '^max_sessions:' | sed 's/max_sessions: *//' || echo "20")
echo "Configuration:"
echo " • Model: $MODEL"
echo " • Max sessions: $MAX_SESSIONS"
echo " • Config: .claude/sdk-bridge.local.md"
echo ""
fi
echo "The handoff command will now proceed to launch the SDK agent."
echo ""
If validation fails, you've already exited with an error message explaining what's wrong and how to fix it.
exit 1 to BLOCK handoff when critical requirements failexit 0 early if there's no work to do (all features passing)Designs feature architectures by analyzing existing codebase patterns and conventions, then providing comprehensive implementation blueprints with specific files to create/modify, component designs, data flows, and build sequences