Collection

---
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:
```json
{
  "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": "INIT", "timestamp": "2025-11-11T12:34:56-05:00"}
  ]
}
```

**⚠️ 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:
```markdown
# 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

```bash
# 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

```bash
# 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

```markdown
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:

```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:

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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"

```bash
# 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"

```bash
# 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"

```bash
# 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