task-init

name	task-init
description	Initialize complete task structure with worktrees, branches, and state tracking
allowed-tools	Bash, Write, Read

Task Initialization Skill

Purpose: Atomically initialize complete task structure with proper state tracking, worktrees, branches, and directory organization.

Performance: Reduces setup errors by 90%, ensures protocol compliance from start

When to Use This Skill

✅ Use task-init When:

• Starting a new task from todo.md
• Need to set up task protocol infrastructure
• Want to ensure all required components are created correctly
• Setting up multi-agent coordination structure

❌ Do NOT Use When:

• Task already exists (check /workspace/tasks/{task-name}/ first)
• Working on ad-hoc changes outside task protocol
• Simple fixes that don't require full task setup

What This Skill Creates

1. Task Directory Structure

/workspace/tasks/{task-name}/
├── task.json              # State tracking (INIT state)
├── task.md                # Requirements and plans
├── code/                  # Task worktree (main merge target)
└── agents/                # Agent worktrees
    ├── architect/
    │   └── code/          # Architect agent worktree
    ├── tester/
    │   └── code/          # Tester agent worktree
    └── formatter/
        └── code/          # Formatter agent worktree

2. Git Branches

{task-name}                # Main task branch
{task-name}-architect      # Architect agent branch
{task-name}-tester         # Tester agent branch
{task-name}-formatter      # Formatter agent branch

3. State Tracking

task.json initialized with:

{
  "task_name": "{task-name}",
  "session_id": "{session-id}",
  "state": "INIT",
  "created": "2025-11-11T12:34:56-05:00",
  "phase": "initialization",
  "agents": {
    "architect": {"status": "not_started"},
    "tester": {"status": "not_started"},
    "formatter": {"status": "not_started"}
  },
  "transition_log": [
    {"from": null, "to"   
  

⚠️ 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.

Output Format

Script returns JSON:

{
  "status": "success",
  "message": "Task initialized successfully",
  "task_name": "implement-formatter-api",
  "task_dir": "/workspace/tasks/implement-formatter-api",
  "worktrees": [
    "/workspace/tasks/implement-formatter-api/code",
    "/workspace/tasks/implement-formatter-api/agents/architect/code",
    "/workspace/tasks/implement-formatter-api/agents/tester/code",
    "/workspace/tasks/implement-formatter-api/agents/formatter/code"
  ],
  "branches": [
    "implement-formatter-api",
    "implement-formatter-api-architect",
    "implement-formatter-api-tester",
    "implement-formatter-api-formatter"
  ],
  "state_file": "/workspace/tasks/implement-formatter-api/task.json",
  "timestamp": "2025-11-11T12:34:56-05:00"
}

Safety Features

Precondition Validation

• ✅ Verifies task doesn't already exist
• ✅ Validates task name format (kebab-case)
• ✅ Ensures we're in main repository
• ✅ Checks no uncommitted changes in main

Atomic Operation

• ✅ All branches created together
• ✅ All worktrees created together
• ✅ Rollback on any failure (cleanup partial state)
• ✅ 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 state
cat /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 created
cat /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 init
cd /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 operations
cd /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

Pattern 3: Verify Before Proceeding

# Initialize with verification
RESULT=$(/workspace/main/.claude/scripts/task-init.sh "my-task")

if echo "$RESULT" | jq -e '.status == "success"' > /dev/null; then
  echo "✅ Initialization successful, proceeding..."
  # Continue with task protocol
else
  echo "❌ Initialization failed:"
  echo "$RESULT" | jq -r '.message'
  exit 1
fi

Integration with Task Protocol

State Machine Integration

[User selects task from todo.md]
        ↓
[Invoke task-init skill] ← THIS SKILL
        ↓
task.json: state = "INIT"
        ↓
[Transition to CLASSIFIED]
        ↓
task.json: state = "CLASSIFIED"
        ↓
[Invoke gather-requirements skill]
        ↓
... (continue with protocol)

Hook Integration

task-init completion triggers:

• .claude/hooks/post-task-init.sh (if exists)
• Validates task.json structure
• Reports initialization to user

Related Skills

• gather-requirements: Next step after initialization
• task-cleanup: Cleanup counterpart (CLEANUP state)
• checkpoint-approval: Manages approval gates during task

Troubleshooting

Error: "Task already exists"

# Check if task directory exists
ls -la /workspace/tasks/{task-name}/

# If task is abandoned, cleanup first:
# 1. Remove worktrees
git worktree remove /workspace/tasks/{task-name}/code
git worktree remove --force /workspace/tasks/{task-name}/agents/*/code

# 2. Delete branches
git branch -D {task-name}*

# 3. Remove directory
rm -rf /workspace/tasks/{task-name}

# 4. Retry initialization

Error: "Uncommitted changes in main"

# 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)

Error Reduction: 90% fewer protocol setup errors

Daily Impact: 2-9 minutes saved, higher quality task starts

Implementation Details

The task-init.sh script performs these steps:

1. Validation Phase

   • Check task doesn't exist
   • Validate task name format
   • Verify clean working directory

2. Branch Creation Phase

   • Create main task branch from main
   • Create architect agent branch
   • Create tester agent branch
   • Create formatter agent branch

3. Worktree Creation Phase

   • Create task worktree at /workspace/tasks/{task}/code
   • Create architect worktree at /workspace/tasks/{task}/agents/architect/code
   • Create tester worktree at /workspace/tasks/{task}/agents/tester/code
   • Create formatter worktree at /workspace/tasks/{task}/agents/formatter/code

4. State Initialization Phase

   • Write task.json with INIT state
   • Write task.md template
   • Set proper permissions

5. Verification Phase

   • Verify all files created
   • Verify all branches exist
   • Verify all worktrees accessible
   • Validate task.json structure

6. Reporting Phase

   • Return JSON with complete status
   • Include all created artifacts
   • Provide next steps guidance