orchestrator

What this skill does

# Orchestrator v2

A **thin coordination layer** with two distinct modes:
- **Plan Mode** (`/plan`) - Decompose spec into task DAG
- **Execute Mode** (`/execute`) - Run tasks via isolated subagents

## Workflow Integration

The full workflow from requirements to implementation:

```
/specify → /plan → /execute
```

| Skill | Purpose | Input | Output |
|-------|---------|-------|--------|
| `/specify` | Design vision & capabilities | User requirements | `{TARGET}/docs/specs/<slug>.md` + `.capabilities.json` + ADRs |
| `/plan` | DAG construction (files → tasks) | Spec + capability map | Task DAG in `.tasker/tasks/` |
| `/execute` | Implementation | Task DAG | Working code |

**Entry points:**
- **From scratch** → Run `/specify` first to develop spec and extract capabilities
- **Existing spec** → Run `/plan {TARGET}/docs/specs/<slug>.md` directly (may need capability extraction)
- **From /specify** → Run `/plan {TARGET}/docs/specs/<slug>.md` (skips to physical mapping)

## Philosophy

The orchestrator does NOT:
- Track state itself (tasker CLI does this)
- Validate artifacts (tasker CLI does this)
- Compute ready tasks (tasker CLI does this)

The orchestrator ONLY:
- Queries state via `tasker state`
- Dispatches agents based on mode/phase
- Handles user interaction
- **Ensures commits happen** via `.claude/hooks/post-task-commit.sh` (defense in depth)

---

## Directory Initialization (After target_dir is known)

**CRITICAL:** After obtaining target_dir from the user, the orchestrator MUST initialize the `.tasker/` directory structure. This is the ONLY place where directories are created - sub-agents assume directories already exist.

### Setup (Run after target_dir is confirmed)

Initialize the `.tasker/` directory structure:

```bash
TASKER_DIR="$TARGET_DIR/.tasker"
mkdir -p "$TASKER_DIR"/{artifacts,inputs,tasks,reports,bundles,logs}
```

This creates:
- `$TARGET_DIR/.tasker/artifacts/` - For capability-map.json, physical-map.json
- `$TARGET_DIR/.tasker/inputs/` - For spec.md
- `$TARGET_DIR/.tasker/tasks/` - For T001.json, T002.json, etc.
- `$TARGET_DIR/.tasker/reports/` - For task-validation-report.md
- `$TARGET_DIR/.tasker/bundles/` - For execution bundles
- `$TARGET_DIR/.tasker/logs/` - For activity logging

Set TASKER_DIR as the working directory for all operations:
```bash
TASKER_DIR="$TARGET_DIR/.tasker"
echo "TASKER_DIR: $TASKER_DIR"
```

**Why centralized initialization?**
1. **Reliability**: Sub-agents run in isolated contexts and directory creation has been unreliable
2. **Single responsibility**: Orchestrator owns the directory structure, sub-agents own the content
3. **Fail-fast**: If directory creation fails, we catch it immediately rather than mid-workflow

**IMPORTANT:** Sub-agents must NOT create directories. They assume the directory structure already exists. If a sub-agent encounters a "directory does not exist" error, it indicates the orchestrator failed to initialize properly.

## Runtime Logging (MANDATORY)

All orchestrator activity and sub-agent activity MUST be logged using `./scripts/log-activity.sh`.

### Logging Script Usage

```bash
./scripts/log-activity.sh <LEVEL> <AGENT> <EVENT> "<MESSAGE>"
```

**Parameters:**
- `LEVEL`: INFO, WARN, ERROR
- `AGENT`: orchestrator, logic-architect, physical-architect, task-author, etc.
- `EVENT`: start, decision, tool, complete, spawn, spawn-complete, phase-transition, validation
- `MESSAGE`: Description of the activity

### Orchestrator Logging Examples

```bash
./scripts/log-activity.sh INFO orchestrator phase-transition "moving from logical to physical"
./scripts/log-activity.sh INFO orchestrator spawn "launching logic-architect for capability extraction"
./scripts/log-activity.sh INFO orchestrator spawn-complete "logic-architect finished with SUCCESS"
./scripts/log-activity.sh INFO orchestrator validation "capability_map - PASSED"
```

### Sub-Agent Logging Instructions

**CRITICAL:** Include these logging instructions in EVERY sub-agent spawn prompt. Sub-agents are context-isolated and will not see this skill file - they must receive logging instructions explicitly.

Add this block to every spawn prompt:

```
## Logging (MANDATORY)

Log your activity using the logging script:

\`\`\`bash
./scripts/log-activity.sh INFO $AGENT_NAME start "Starting task description"
./scripts/log-activity.sh INFO $AGENT_NAME decision "What decision and why"
./scripts/log-activity.sh INFO $AGENT_NAME complete "Outcome description"
./scripts/log-activity.sh WARN $AGENT_NAME warning "Warning message"
./scripts/log-activity.sh ERROR $AGENT_NAME error "Error message"
\`\`\`

Replace $AGENT_NAME with your agent name (e.g., logic-architect, task-executor).
```

## CRITICAL: Path Management

**TASKER_DIR must be an absolute path.** Sub-agents run in isolated contexts and cannot resolve relative paths correctly.

After obtaining target_dir from user, compute and store:
```bash
# Get absolute path to .tasker directory within target project
TARGET_DIR="<user-provided-absolute-path>"
TASKER_DIR="$TARGET_DIR/.tasker"
echo "TASKER_DIR: $TASKER_DIR"
```

This `TASKER_DIR` value (e.g., `/Users/foo/my-project/.tasker`) MUST be passed to every sub-agent spawn. Do NOT use relative paths like `.tasker/` in spawn prompts.

**NOTE:** Throughout this document, `TASKER_DIR` replaces the old `PLANNING_DIR` variable. They serve the same purpose.

---

# Plan Mode

Triggered by `/plan`. Runs phases 0-6 (spec review through ready).

## MANDATORY FIRST STEP: Ask for Target Project Directory

**ALWAYS ask for target_dir FIRST before anything else.** No guessing, no inference from CWD.

### Step 1: Ask for Target Directory

Use AskUserQuestion to ask:
```
What is the target project directory?
```
Free-form text input. User must provide an absolute or relative path.

**Validation:**
```bash
TARGET_DIR="<user-provided-path>"
# Convert to absolute path
TARGET_DIR=$(cd "$TARGET_DIR" 2>/dev/null && pwd || echo "$TARGET_DIR")

if [ ! -d "$TARGET_DIR" ]; then
    # For new projects, check parent exists
    PARENT=$(dirname "$TARGET_DIR")
    if [ -d "$PARENT" ]; then
        echo "Directory will be created: $TARGET_DIR"
        mkdir -p "$TARGET_DIR"
    else
        echo "Error: Parent directory does not exist: $PARENT"
        # Re-ask for target_dir
    fi
fi
```

### Step 2: Check for Existing Session and Initialize

After target_dir is confirmed, check for existing `.tasker/` state:

```bash
TASKER_DIR="$TARGET_DIR/.tasker"
if [ -f "$TASKER_DIR/state.json" ]; then
    echo "Found existing tasker session at $TASKER_DIR"
    echo "Resuming from saved state..."
    # Read phase from state.json and resume
    tasker state status
else
    echo "No existing session. Initializing..."
    # Initialize directory structure (see Directory Initialization below)
fi
```

### Step 3: Detect Specs (Automatic)

**Specs are REQUIRED for /plan to proceed.** Check `$TARGET_DIR/docs/specs/` for specs from /specify:

```bash
SPEC_DIR="$TARGET_DIR/docs/specs"

# Find spec files (from /specify workflow)
SPEC_FILES=$(find "$SPEC_DIR" -maxdepth 1 -name "*.md" 2>/dev/null)
CAP_MAPS=$(find "$SPEC_DIR" -maxdepth 1 -name "*.capabilities.json" 2>/dev/null)

if [ -n "$SPEC_FILES" ]; then
    echo "=== Specs found ==="
    echo "$SPEC_FILES"

    # Use the first spec (or only spec)
    SPEC_PATH=$(echo "$SPEC_FILES" | head -1)
    SPEC_SLUG=$(basename "$SPEC_PATH" .md)

    # Check for matching capability map
    CAP_MAP="$SPEC_DIR/${SPEC_SLUG}.capabilities.json"
    if [ -f "$CAP_MAP" ]; then
        echo "Capability map found: $CAP_MAP"
        echo "Can skip logic-architect phase"
    fi
else
    echo "No specs found in $SPEC_DIR"
    # BLOCK - see below
fi
```

### If spec found:

Proceed to Step 4. No user question needed.

### If NO spec found — BLOCK and offer /specify:

**/plan CANNOT proceed without specs.** Present this to the user:

```markdown
## Specs Required

Planning requires a specification to decompose into tasks. Without a spec, there's nothing t