⚠️ CRITICAL: The session_id field tracks which Claude instance owns the task. Other instances
MUST NOT work on tasks with a different session_id (see CLAUDE.md § Session Ownership Verification).
task.md initialized with template:
# Task: {task-name}## Status: INIT## Requirements
[To be filled by stakeholder agents in REQUIREMENTS phase]
## Implementation Plan
[To be synthesized in SYNTHESIS phase]
Usage
Basic Task Initialization
# Step 1: Invoke skill with task name and session ID# Task name should match entry in todo.md# Session ID comes from system reminder at SessionStart
TASK_NAME="implement-formatter-api"
SESSION_ID="your-session-id-from-startup"# ← REQUIRED for ownership tracking# Step 2: Execute initialization script
/workspace/main/.claude/scripts/task-init.sh "$TASK_NAME""""$SESSION_ID"
With Custom Description
# Pass task description and session ID
TASK_NAME="implement-formatter-api"
DESCRIPTION="Add public API for custom formatting rules"
SESSION_ID="your-session-id"
/workspace/main/.claude/scripts/task-init.sh "$TASK_NAME""$DESCRIPTION""$SESSION_ID"
⚠️ IMPORTANT: Always pass your session ID (from SessionStart hook) to track task ownership.
Tasks without session_id cannot be properly coordinated across multiple Claude instances.
Workflow Integration
Complete Task Startup Sequence
1. ✅ User selects task from todo.md
2. ✅ Invoke task-init skill
3. ✅ Verify initialization successful
4. ⚠️ CHANGE TO TASK WORKTREE: `cd /workspace/tasks/{task-name}/code`5. ✅ Verify directory: `pwd` (must show task worktree path)
6. ✅ Transition to CLASSIFIED state
7. ✅ Invoke gather-requirements skill
8. Continue with task protocol...
⚠️ CRITICAL: After task-init, you MUST change to the task worktree before continuing.
Main agent operations during task protocol should run from /workspace/tasks/{task-name}/code/,
NOT from /workspace/main/.
NEVER checkout task branch in /workspace/main:
❌ WRONG: git checkout {task-name} (in /workspace/main)
✅ CORRECT: cd /workspace/tasks/{task-name}/code (already on task branch)
The task worktree is ALREADY on the task branch. Do NOT checkout the branch in main - this
violates isolation and is blocked by the block-main-task-branch-checkout.sh hook.
✅ State tracking initialized last (after infrastructure ready)
Error Handling
On any error, script:
Exits immediately with clear error message
Returns JSON with error status and details
Cleans up any partially created infrastructure
Leaves repository in clean state
Recovery: If script fails, safe to retry after fixing issue
Verification Steps
After initialization, verify:
# 1. Check task.json exists and has correct statecat /workspace/tasks/{task-name}/task.json | jq '.state'# Should output: "INIT"# 2. Verify all worktrees created
git worktree list | grep {task-name}
# Should show 4 worktrees# 3. Verify all branches exist
git branch | grep {task-name}
# Should show 4 branches# 4. Check task.md template createdcat /workspace/tasks/{task-name}/task.md
# Should show template with task name
Common Patterns
Pattern 1: Initialize and Immediately Classify
# Initialize task
/workspace/main/.claude/scripts/task-init.sh "implement-api"# ⚠️ CRITICAL: Change to task worktree IMMEDIATELY after initcd /workspace/tasks/implement-api/code
pwd# Verify: must show /workspace/tasks/implement-api/code# Transition to CLASSIFIED (ready for requirements gathering)cd /workspace/tasks/implement-api # task root for task.json
jq '.state = "CLASSIFIED" | .phase = "requirements"' task.json > tmp.json
mv tmp.json task.json
# Return to task worktree for all subsequent operationscd /workspace/tasks/implement-api/code
Pattern 2: Initialize Multiple Tasks
# For batch task setup (rare, but useful)for task in"task-1""task-2""task-3"; do
/workspace/main/.claude/scripts/task-init.sh "$task"done
# Stash or commit changes before initializing task
git stash
# OR
git add -A && git commit -m "WIP: preparing for task init"# Then retry initialization
Error: "Invalid task name format"
# Task names must be kebab-case# ✅ CORRECT: "implement-formatter-api"# ❌ WRONG: "Implement Formatter API"# ❌ WRONG: "implement_formatter_api"# Convert to kebab-case:
TASK_NAME=$(echo"My Task Name" | tr'[:upper:]''[:lower:]' | tr' ''-')
Performance Impact
Expected Usage: 1-3 times per day
Time Savings per Use: ~2-3 minutes (setup + verification)