phase-task-verification
Shared branch creation and verification logic for sequential and parallel task execution - handles git operations, HEAD verification, and MODE-specific behavior
When & Why to Use This Skill
This Claude skill provides a robust framework for automated Git branch management and task verification. It streamlines the lifecycle of coding tasks by handling branch creation, staging changes, and performing critical HEAD state checks for both sequential and parallel execution modes. By implementing strict verification logic and comprehensive error handling, it prevents silent failures and ensures repository integrity during complex automated development workflows.
Use Cases
- Automated Workflow Orchestration: Standardizing how AI agents create and verify Git branches during multi-step coding tasks to ensure work is never lost.
- Parallel Task Execution: Managing detached HEAD states in parallel environments to allow multiple concurrent operations without branch naming conflicts or worktree corruption.
- CI/CD Pipeline Integration: Using the verification logic as a pre-commit or post-task check to ensure that automated changes are correctly staged and branched before merging.
- Error Recovery and Debugging: Utilizing the built-in rationalization and error handling to identify and resolve Git state issues like duplicate branches or permission errors automatically.
| name | phase-task-verification |
|---|---|
| description | Shared branch creation and verification logic for sequential and parallel task execution - handles git operations, HEAD verification, and MODE-specific behavior |
Phase Task Verification
When to Use
Invoked by sequential-phase-task and parallel-phase-task after task implementation to create and verify git-spice branch.
Parameters
- RUN_ID: 6-char run ID (e.g., "8c8505")
- TASK_ID: Phase-task (e.g., "1-1")
- TASK_NAME: Short name (e.g., "create-verification-skill")
- COMMIT_MESSAGE: Full commit message
- MODE: "sequential" or "parallel"
The Process
Step 1: Stage and create branch
git add .
gs branch create {RUN_ID}-task-{TASK_ID}-{TASK_NAME} -m "{COMMIT_MESSAGE}"
Step 2: Verify based on MODE
MODE: sequential - Verify HEAD points to expected branch:
CURRENT=$(git rev-parse --abbrev-ref HEAD)
EXPECTED="{RUN_ID}-task-{TASK_ID}-{TASK_NAME}"
[ "$CURRENT" = "$EXPECTED" ] || { echo "ERROR: HEAD=$CURRENT, expected $EXPECTED"; exit 1; }
MODE: parallel - Detach HEAD (makes branch accessible in parent repo):
git switch --detach
CURRENT=$(git rev-parse --abbrev-ref HEAD)
[ "$CURRENT" = "HEAD" ] || { echo "ERROR: HEAD not detached ($CURRENT)"; exit 1; }
Rationalization Table
| Rationalization | Why It's Wrong |
|---|---|
| "Verification is optional" | Silent failures lose work |
| "Skip detach in parallel mode" | Breaks worktree cleanup |
| "Branch create errors are obvious" | Silent failures aren't detected until cleanup fails |
| "Detach can happen later" | Cleanup runs in parent repo - branch must be accessible |
| "HEAD verification adds overhead" | <100ms cost prevents hours of lost work debugging |
Error Handling
git add fails:
- No changes to stage: Error is expected - task implementation failed or incomplete
- Check if task was actually implemented
- Verify files were modified in expected locations
- Do NOT continue with branch creation
- Permission issues: Git repository permissions corrupted
- Check file ownership:
ls -la .git - Verify worktree is accessible
- Escalate to orchestrator
- Check file ownership:
gs branch create fails:
- Duplicate branch name: Branch already exists
- Check existing branches:
git branch | grep {RUN_ID}-task-{TASK_ID} - Verify task wasn't already completed
- May indicate resume scenario - escalate to orchestrator
- Check existing branches:
- Git-spice errors: Repository state issues
- Run
gs repo syncto fix state - Verify git-spice initialized:
gs ls - Check for uncommitted changes blocking operation
- Run
- Invalid branch name: Name contains invalid characters
- Verify RUN_ID is 6-char alphanumeric
- Verify TASK_NAME contains only alphanumeric + hyphens
- Do NOT sanitize - escalate to orchestrator (indicates data corruption)
HEAD verification fails (sequential mode):
- Expected:
gs branch createshould checkout new branch automatically - Actual: Still on previous branch or detached HEAD
- Indicates git-spice behavior change or bug
- Do NOT continue - task is not properly staged
- Escalate to orchestrator with exact HEAD state
HEAD verification fails (parallel mode):
- Expected:
git switch --detachshould detach HEAD - Actual: Still on branch after detach command
- Indicates git version issue or repository corruption
- Do NOT continue - cleanup will fail to access branch
- Escalate to orchestrator with git version:
git --version